@btst/stack 2.8.1 → 2.9.1

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

@@ -0,0 +1,60 @@
+import { S as S3StorageAdapter } from '../../../../shared/stack.BttDsJJn.mjs';
+
+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 };

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

@@ -0,0 +1,60 @@
+import { S as S3StorageAdapter } from '../../../../shared/stack.BttDsJJn.js';
+
+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 };

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

@@ -0,0 +1,104 @@
+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 }));
+    }
+  };
+}
+
+export { s3Adapter };

package/dist/plugins/media/api/adapters/vercel-blob.cjs

@@ -0,0 +1,53 @@
+'use strict';
+
+function vercelBlobAdapter(options = {}) {
+  return {
+    type: "vercel-blob",
+    urlHostnameSuffix: ".public.blob.vercel-storage.com",
+    async handleRequest(request, callbacks) {
+      let handleUpload;
+      try {
+        const vercelBlobClient = (
+          /* @vite-ignore */
+          await import('@vercel/blob/client')
+        );
+        ({ handleUpload } = vercelBlobClient);
+      } catch {
+        throw new Error(
+          "[@btst/stack] Vercel Blob adapter requires '@vercel/blob' with 'handleUpload' exported from '@vercel/blob/client'. Run: npm install @vercel/blob"
+        );
+      }
+      const body = await request.json();
+      return handleUpload({
+        body,
+        request,
+        token: options.token,
+        onBeforeGenerateToken: async (pathname, clientPayload) => {
+          const tokenOptions = await callbacks.onBeforeGenerateToken?.(
+            pathname,
+            clientPayload ?? null
+          ) ?? {};
+          return {
+            addRandomSuffix: true,
+            ...tokenOptions
+          };
+        },
+        onUploadCompleted: async () => {
+        }
+      });
+    },
+    async delete(url) {
+      let del;
+      try {
+        ({ del } = await import('@vercel/blob'));
+      } catch {
+        throw new Error(
+          "[@btst/stack] Vercel Blob adapter requires '@vercel/blob'. Run: npm install @vercel/blob"
+        );
+      }
+      await del(url, options.token ? { token: options.token } : void 0);
+    }
+  };
+}
+
+exports.vercelBlobAdapter = vercelBlobAdapter;

package/dist/plugins/media/api/adapters/vercel-blob.d.cts

@@ -0,0 +1,41 @@
+import { V as VercelBlobStorageAdapter } from '../../../../shared/stack.BttDsJJn.cjs';
+
+interface VercelBlobStorageAdapterOptions {
+    /**
+     * The `BLOB_READ_WRITE_TOKEN` environment variable is read automatically
+     * by `@vercel/blob`. You only need to provide this option if you store
+     * the token under a different name.
+     */
+    token?: string;
+}
+/**
+ * Create a Vercel Blob storage adapter using the signed direct-upload protocol.
+ * The server never receives file bytes — it only issues short-lived client tokens
+ * via `@vercel/blob`'s `handleUpload` helper (available via `@vercel/blob/client`
+ * in compatible versions).
+ *
+ * @remarks Requires `@vercel/blob` as an optional peer dependency (version
+ * with `handleUpload` exported from `@vercel/blob/client`).
+ *
+ * Upload flow:
+ * 1. Client calls `POST /media/upload/vercel-blob` to obtain a client token.
+ * 2. Client uses `@vercel/blob/client`'s `upload()` to upload directly to Vercel.
+ * 3. After upload, client calls `POST /media/assets` to save metadata to the DB.
+ *
+ * @example
+ * ```ts
+ * mediaBackendPlugin({
+ *   storageAdapter: vercelBlobAdapter(),
+ *   hooks: {
+ *     onBeforeUpload: async (_meta, ctx) => {
+ *       const session = await getSession(ctx.headers);
+ *       if (!session) throw new Error("Unauthorized");
+ *     },
+ *   },
+ * })
+ * ```
+ */
+declare function vercelBlobAdapter(options?: VercelBlobStorageAdapterOptions): VercelBlobStorageAdapter;
+
+export { vercelBlobAdapter };
+export type { VercelBlobStorageAdapterOptions };

package/dist/plugins/media/api/adapters/vercel-blob.d.mts

@@ -0,0 +1,41 @@
+import { V as VercelBlobStorageAdapter } from '../../../../shared/stack.BttDsJJn.mjs';
+
+interface VercelBlobStorageAdapterOptions {
+    /**
+     * The `BLOB_READ_WRITE_TOKEN` environment variable is read automatically
+     * by `@vercel/blob`. You only need to provide this option if you store
+     * the token under a different name.
+     */
+    token?: string;
+}
+/**
+ * Create a Vercel Blob storage adapter using the signed direct-upload protocol.
+ * The server never receives file bytes — it only issues short-lived client tokens
+ * via `@vercel/blob`'s `handleUpload` helper (available via `@vercel/blob/client`
+ * in compatible versions).
+ *
+ * @remarks Requires `@vercel/blob` as an optional peer dependency (version
+ * with `handleUpload` exported from `@vercel/blob/client`).
+ *
+ * Upload flow:
+ * 1. Client calls `POST /media/upload/vercel-blob` to obtain a client token.
+ * 2. Client uses `@vercel/blob/client`'s `upload()` to upload directly to Vercel.
+ * 3. After upload, client calls `POST /media/assets` to save metadata to the DB.
+ *
+ * @example
+ * ```ts
+ * mediaBackendPlugin({
+ *   storageAdapter: vercelBlobAdapter(),
+ *   hooks: {
+ *     onBeforeUpload: async (_meta, ctx) => {
+ *       const session = await getSession(ctx.headers);
+ *       if (!session) throw new Error("Unauthorized");
+ *     },
+ *   },
+ * })
+ * ```
+ */
+declare function vercelBlobAdapter(options?: VercelBlobStorageAdapterOptions): VercelBlobStorageAdapter;
+
+export { vercelBlobAdapter };
+export type { VercelBlobStorageAdapterOptions };

package/dist/plugins/media/api/adapters/vercel-blob.d.ts

@@ -0,0 +1,41 @@
+import { V as VercelBlobStorageAdapter } from '../../../../shared/stack.BttDsJJn.js';
+
+interface VercelBlobStorageAdapterOptions {
+    /**
+     * The `BLOB_READ_WRITE_TOKEN` environment variable is read automatically
+     * by `@vercel/blob`. You only need to provide this option if you store
+     * the token under a different name.
+     */
+    token?: string;
+}
+/**
+ * Create a Vercel Blob storage adapter using the signed direct-upload protocol.
+ * The server never receives file bytes — it only issues short-lived client tokens
+ * via `@vercel/blob`'s `handleUpload` helper (available via `@vercel/blob/client`
+ * in compatible versions).
+ *
+ * @remarks Requires `@vercel/blob` as an optional peer dependency (version
+ * with `handleUpload` exported from `@vercel/blob/client`).
+ *
+ * Upload flow:
+ * 1. Client calls `POST /media/upload/vercel-blob` to obtain a client token.
+ * 2. Client uses `@vercel/blob/client`'s `upload()` to upload directly to Vercel.
+ * 3. After upload, client calls `POST /media/assets` to save metadata to the DB.
+ *
+ * @example
+ * ```ts
+ * mediaBackendPlugin({
+ *   storageAdapter: vercelBlobAdapter(),
+ *   hooks: {
+ *     onBeforeUpload: async (_meta, ctx) => {
+ *       const session = await getSession(ctx.headers);
+ *       if (!session) throw new Error("Unauthorized");
+ *     },
+ *   },
+ * })
+ * ```
+ */
+declare function vercelBlobAdapter(options?: VercelBlobStorageAdapterOptions): VercelBlobStorageAdapter;
+
+export { vercelBlobAdapter };
+export type { VercelBlobStorageAdapterOptions };

package/dist/plugins/media/api/adapters/vercel-blob.mjs

@@ -0,0 +1,51 @@
+function vercelBlobAdapter(options = {}) {
+  return {
+    type: "vercel-blob",
+    urlHostnameSuffix: ".public.blob.vercel-storage.com",
+    async handleRequest(request, callbacks) {
+      let handleUpload;
+      try {
+        const vercelBlobClient = (
+          /* @vite-ignore */
+          await import('@vercel/blob/client')
+        );
+        ({ handleUpload } = vercelBlobClient);
+      } catch {
+        throw new Error(
+          "[@btst/stack] Vercel Blob adapter requires '@vercel/blob' with 'handleUpload' exported from '@vercel/blob/client'. Run: npm install @vercel/blob"
+        );
+      }
+      const body = await request.json();
+      return handleUpload({
+        body,
+        request,
+        token: options.token,
+        onBeforeGenerateToken: async (pathname, clientPayload) => {
+          const tokenOptions = await callbacks.onBeforeGenerateToken?.(
+            pathname,
+            clientPayload ?? null
+          ) ?? {};
+          return {
+            addRandomSuffix: true,
+            ...tokenOptions
+          };
+        },
+        onUploadCompleted: async () => {
+        }
+      });
+    },
+    async delete(url) {
+      let del;
+      try {
+        ({ del } = await import('@vercel/blob'));
+      } catch {
+        throw new Error(
+          "[@btst/stack] Vercel Blob adapter requires '@vercel/blob'. Run: npm install @vercel/blob"
+        );
+      }
+      await del(url, options.token ? { token: options.token } : void 0);
+    }
+  };
+}
+
+export { vercelBlobAdapter };

package/dist/plugins/media/api/index.cjs

@@ -0,0 +1,26 @@
+'use strict';
+
+const plugin = require('../../../packages/stack/src/plugins/media/api/plugin.cjs');
+const getters = require('../../../packages/stack/src/plugins/media/api/getters.cjs');
+const mutations = require('../../../packages/stack/src/plugins/media/api/mutations.cjs');
+const serializers = require('../../../packages/stack/src/plugins/media/api/serializers.cjs');
+const queryKeyDefs = require('../../../packages/stack/src/plugins/media/api/query-key-defs.cjs');
+const local = require('../../../packages/stack/src/plugins/media/api/adapters/local.cjs');
+
+
+
+exports.mediaBackendPlugin = plugin.mediaBackendPlugin;
+exports.getAssetById = getters.getAssetById;
+exports.getFolderById = getters.getFolderById;
+exports.listAssets = getters.listAssets;
+exports.listFolders = getters.listFolders;
+exports.createAsset = mutations.createAsset;
+exports.createFolder = mutations.createFolder;
+exports.deleteAsset = mutations.deleteAsset;
+exports.deleteFolder = mutations.deleteFolder;
+exports.updateAsset = mutations.updateAsset;
+exports.serializeAsset = serializers.serializeAsset;
+exports.serializeFolder = serializers.serializeFolder;
+exports.MEDIA_QUERY_KEYS = queryKeyDefs.MEDIA_QUERY_KEYS;
+exports.assetListDiscriminator = queryKeyDefs.assetListDiscriminator;
+exports.localAdapter = local.localAdapter;

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

@@ -0,0 +1,116 @@
+export { a as MEDIA_QUERY_KEYS, c as MediaApiContext, M as MediaApiRouter, e as MediaBackendConfig, d as MediaBackendHooks, b as assetListDiscriminator, m as mediaBackendPlugin } from '../../../shared/stack.CI8iRKKi.cjs';
+export { A as AssetListParams, c as AssetListResult, F as FolderListParams, g as getAssetById, b as getFolderById, l as listAssets, a as listFolders } from '../../../shared/stack.CAni8dnD.cjs';
+import { DBAdapter } from '@btst/db';
+import { A as Asset, F as Folder, S as SerializedAsset, a as SerializedFolder } from '../../../shared/stack.CLcnSF_b.cjs';
+import { D as DirectStorageAdapter } from '../../../shared/stack.BttDsJJn.cjs';
+export { S as S3StorageAdapter, b as S3UploadToken, a as StorageAdapter, U as UploadOptions, c as VercelBlobHandlerCallbacks, V as VercelBlobStorageAdapter } from '../../../shared/stack.BttDsJJn.cjs';
+import '@btst/stack/plugins/api';
+import 'better-call';
+import 'zod';
+
+/**
+ * Input for creating a new asset record.
+ */
+interface CreateAssetInput {
+    filename: string;
+    originalName: string;
+    mimeType: string;
+    size: number;
+    url: string;
+    folderId?: string;
+    alt?: string;
+}
+/**
+ * Input for updating an existing asset record.
+ */
+interface UpdateAssetInput {
+    alt?: string;
+    folderId?: string | null;
+}
+/**
+ * Input for creating a new folder.
+ */
+interface CreateFolderInput {
+    name: string;
+    parentId?: string;
+}
+/**
+ * Create an asset record in the database.
+ * Pure DB function — no authorization hooks, no HTTP context.
+ *
+ * @remarks **Security:** No authorization hooks (e.g. `onBeforeUpload`) are called.
+ * The caller is responsible for any access-control checks before invoking this function.
+ */
+declare function createAsset(adapter: DBAdapter, input: CreateAssetInput): Promise<Asset>;
+/**
+ * Update an asset's `alt` text or `folderId`.
+ * Pure DB function — no authorization hooks, no HTTP context.
+ *
+ * @remarks **Security:** No authorization hooks are called.
+ */
+declare function updateAsset(adapter: DBAdapter, id: string, input: UpdateAssetInput): Promise<Asset | null>;
+/**
+ * Delete an asset record from the database by its ID.
+ * Does NOT delete the underlying file — the caller must do that via the storage adapter.
+ * Pure DB function — no authorization hooks, no HTTP context.
+ *
+ * @remarks **Security:** No authorization hooks are called.
+ */
+declare function deleteAsset(adapter: DBAdapter, id: string): Promise<void>;
+/**
+ * Create a folder record in the database.
+ * Pure DB function — no authorization hooks, no HTTP context.
+ *
+ * @remarks **Security:** No authorization hooks are called.
+ */
+declare function createFolder(adapter: DBAdapter, input: CreateFolderInput): Promise<Folder>;
+/**
+ * Delete a folder record from the database by its ID.
+ * Child folders are cascade-deleted automatically. Throws if the folder or
+ * any of its descendants contain assets (which have associated storage files
+ * that must be deleted via the storage adapter first).
+ * Pure DB function — no authorization hooks, no HTTP context.
+ *
+ * @remarks **Security:** No authorization hooks are called.
+ */
+declare function deleteFolder(adapter: DBAdapter, id: string): Promise<void>;
+
+/**
+ * Serialize an Asset for SSR/SSG use (convert dates to strings).
+ * Pure function — no DB access, no hooks.
+ */
+declare function serializeAsset(asset: Asset): SerializedAsset;
+/**
+ * Serialize a Folder for SSR/SSG use (convert dates to strings).
+ * Pure function — no DB access, no hooks.
+ */
+declare function serializeFolder(folder: Folder): SerializedFolder;
+
+interface LocalStorageAdapterOptions {
+    /**
+     * Absolute path to the directory where uploaded files are stored.
+     * @default "./public/uploads"
+     */
+    uploadDir?: string;
+    /**
+     * URL prefix used to build the public URL for uploaded files.
+     * @default "/uploads"
+     */
+    publicPath?: string;
+}
+/**
+ * Create a local filesystem storage adapter.
+ * Files are written to `uploadDir` and served at `publicPath`.
+ * Suitable for development and self-hosted deployments.
+ *
+ * @example
+ * ```ts
+ * mediaBackendPlugin({
+ *   storageAdapter: localAdapter({ uploadDir: "./public/uploads", publicPath: "/uploads" })
+ * })
+ * ```
+ */
+declare function localAdapter(options?: LocalStorageAdapterOptions): DirectStorageAdapter;
+
+export { DirectStorageAdapter, createAsset, createFolder, deleteAsset, deleteFolder, localAdapter, serializeAsset, serializeFolder, updateAsset };
+export type { CreateAssetInput, CreateFolderInput, LocalStorageAdapterOptions, UpdateAssetInput };