@btst/stack 2.8.1 → 2.9.1

package/dist/packages/stack/src/plugins/media/api/plugin.mjs

@@ -0,0 +1,523 @@
+import { defineBackendPlugin, createEndpoint } from '@btst/stack/plugins/api';
+import { z } from 'zod';
+import { mediaSchema } from '../db.mjs';
+import { AssetListQuerySchema, createAssetSchema, updateAssetSchema, createFolderSchema, uploadTokenRequestSchema } from '../schemas.mjs';
+import { getFolderById, listFolders, getAssetById, listAssets } from './getters.mjs';
+import { createAsset, updateAsset, deleteAsset, createFolder, deleteFolder } from './mutations.mjs';
+import { isDirectAdapter, isS3Adapter, isVercelBlobAdapter } from './storage-adapter.mjs';
+import { runHookWithShim } from '../../utils.mjs';
+
+function sanitizeS3KeySegment(s) {
+  return s.replace(/[/\\]/g, "-").replace(/\.\./g, "_").trim() || "unknown";
+}
+function matchesUrlPrefix(url, prefix) {
+  const normalizedPrefix = `${prefix.replace(/\/+$/, "")}/`;
+  return url.startsWith(normalizedPrefix);
+}
+const mediaBackendPlugin = (config) => defineBackendPlugin({
+  name: "media",
+  dbPlugin: mediaSchema,
+  api: (adapter) => ({
+    listAssets: (params) => listAssets(adapter, params),
+    getAssetById: (id) => getAssetById(adapter, id),
+    listFolders: (params) => listFolders(adapter, params),
+    getFolderById: (id) => getFolderById(adapter, id)
+  }),
+  routes: (adapter) => {
+    const {
+      storageAdapter,
+      maxFileSizeBytes = 10 * 1024 * 1024,
+      allowedMimeTypes,
+      allowedUrlPrefixes,
+      hooks
+    } = config;
+    function validateMimeType(mimeType, ctx) {
+      if (allowedMimeTypes && allowedMimeTypes.length > 0) {
+        const allowed = allowedMimeTypes.some((pattern) => {
+          if (pattern.endsWith("/*")) {
+            return mimeType.startsWith(pattern.slice(0, -1));
+          }
+          return mimeType === pattern;
+        });
+        if (!allowed) {
+          throw ctx.error(415, {
+            message: `MIME type '${mimeType}' is not allowed. Allowed: ${allowedMimeTypes.join(", ")}`
+          });
+        }
+      }
+    }
+    const listAssetsEndpoint = createEndpoint(
+      "/media/assets",
+      {
+        method: "GET",
+        query: AssetListQuerySchema
+      },
+      async (ctx) => {
+        const { query, headers } = ctx;
+        const context = { query, headers };
+        if (hooks?.onBeforeListAssets) {
+          await runHookWithShim(
+            () => hooks.onBeforeListAssets(query, context),
+            ctx.error,
+            "Unauthorized: Cannot list assets"
+          );
+        }
+        return listAssets(adapter, query);
+      }
+    );
+    const createAssetEndpoint = createEndpoint(
+      "/media/assets",
+      {
+        method: "POST",
+        body: createAssetSchema
+      },
+      async (ctx) => {
+        const context = {
+          body: ctx.body,
+          headers: ctx.headers
+        };
+        if (hooks?.onBeforeUpload) {
+          await runHookWithShim(
+            () => hooks.onBeforeUpload(
+              {
+                filename: ctx.body.filename,
+                mimeType: ctx.body.mimeType,
+                size: ctx.body.size
+              },
+              context
+            ),
+            ctx.error,
+            "Unauthorized: Cannot upload asset"
+          );
+        }
+        validateMimeType(ctx.body.mimeType, ctx);
+        if (ctx.body.size > maxFileSizeBytes) {
+          throw ctx.error(413, {
+            message: `File size ${ctx.body.size} bytes exceeds the limit of ${maxFileSizeBytes} bytes`
+          });
+        }
+        {
+          const url = ctx.body.url;
+          let urlAllowed = true;
+          let denialReason = "";
+          if (allowedUrlPrefixes && allowedUrlPrefixes.length > 0) {
+            urlAllowed = allowedUrlPrefixes.some(
+              (p) => matchesUrlPrefix(url, p)
+            );
+            denialReason = `URL must start with one of: ${allowedUrlPrefixes.join(", ")}`;
+          } else if (isDirectAdapter(storageAdapter)) {
+            urlAllowed = false;
+            denialReason = "Client-supplied asset URLs are not allowed with localAdapter. Use POST /media/upload instead, or configure allowedUrlPrefixes to explicitly allow trusted URL prefixes.";
+          } else if (isS3Adapter(storageAdapter)) {
+            urlAllowed = matchesUrlPrefix(url, storageAdapter.urlPrefix);
+            denialReason = `URL must start with the configured S3 publicBaseUrl: ${storageAdapter.urlPrefix}`;
+          } else if (isVercelBlobAdapter(storageAdapter)) {
+            try {
+              const hostname = new URL(url).hostname;
+              urlAllowed = hostname.endsWith(
+                storageAdapter.urlHostnameSuffix
+              );
+            } catch {
+              urlAllowed = false;
+            }
+            denialReason = `URL hostname must end with ${storageAdapter.urlHostnameSuffix}`;
+          }
+          if (!urlAllowed) {
+            throw ctx.error(400, { message: denialReason });
+          }
+        }
+        if (ctx.body.folderId) {
+          const folder = await getFolderById(adapter, ctx.body.folderId);
+          if (!folder) {
+            throw ctx.error(404, { message: "Folder not found" });
+          }
+        }
+        const asset = await createAsset(adapter, ctx.body);
+        if (hooks?.onAfterUpload) {
+          await hooks.onAfterUpload(asset, context);
+        }
+        return asset;
+      }
+    );
+    const updateAssetEndpoint = createEndpoint(
+      "/media/assets/:id",
+      {
+        method: "PATCH",
+        body: updateAssetSchema
+      },
+      async (ctx) => {
+        const existing = await getAssetById(adapter, ctx.params.id);
+        if (!existing) {
+          throw ctx.error(404, { message: "Asset not found" });
+        }
+        const context = {
+          body: ctx.body,
+          params: ctx.params,
+          headers: ctx.headers
+        };
+        if (hooks?.onBeforeUpdateAsset) {
+          await runHookWithShim(
+            () => hooks.onBeforeUpdateAsset(existing, ctx.body, context),
+            ctx.error,
+            "Unauthorized: Cannot update asset"
+          );
+        }
+        if (ctx.body.folderId != null) {
+          const folder = await getFolderById(adapter, ctx.body.folderId);
+          if (!folder) {
+            throw ctx.error(404, { message: "Folder not found" });
+          }
+        }
+        const updated = await updateAsset(adapter, ctx.params.id, ctx.body);
+        if (!updated) {
+          throw ctx.error(404, { message: "Asset not found" });
+        }
+        return updated;
+      }
+    );
+    const deleteAssetEndpoint = createEndpoint(
+      "/media/assets/:id",
+      {
+        method: "DELETE"
+      },
+      async (ctx) => {
+        const context = {
+          params: ctx.params,
+          headers: ctx.headers
+        };
+        const asset = await getAssetById(adapter, ctx.params.id);
+        if (!asset) {
+          throw ctx.error(404, { message: "Asset not found" });
+        }
+        if (hooks?.onBeforeDelete) {
+          await runHookWithShim(
+            () => hooks.onBeforeDelete(asset, context),
+            ctx.error,
+            "Unauthorized: Cannot delete asset"
+          );
+        }
+        try {
+          await storageAdapter.delete(asset.url);
+        } catch (err) {
+          console.error(
+            `[btst/media] Failed to delete file from storage: ${asset.url}`,
+            err
+          );
+          throw ctx.error(500, {
+            message: "Failed to delete file from storage"
+          });
+        }
+        await deleteAsset(adapter, ctx.params.id);
+        if (hooks?.onAfterDelete) {
+          await hooks.onAfterDelete(ctx.params.id, context);
+        }
+        return { success: true };
+      }
+    );
+    const listFoldersEndpoint = createEndpoint(
+      "/media/folders",
+      {
+        method: "GET",
+        query: z.object({
+          parentId: z.string().optional()
+        })
+      },
+      async (ctx) => {
+        const filter = { parentId: ctx.query.parentId };
+        const context = {
+          query: ctx.query,
+          headers: ctx.headers
+        };
+        if (hooks?.onBeforeListFolders) {
+          await runHookWithShim(
+            () => hooks.onBeforeListFolders(filter, context),
+            ctx.error,
+            "Unauthorized: Cannot list folders"
+          );
+        }
+        return listFolders(adapter, filter);
+      }
+    );
+    const createFolderEndpoint = createEndpoint(
+      "/media/folders",
+      {
+        method: "POST",
+        body: createFolderSchema
+      },
+      async (ctx) => {
+        const context = {
+          body: ctx.body,
+          headers: ctx.headers
+        };
+        if (hooks?.onBeforeCreateFolder) {
+          await runHookWithShim(
+            () => hooks.onBeforeCreateFolder(ctx.body, context),
+            ctx.error,
+            "Unauthorized: Cannot create folder"
+          );
+        }
+        return createFolder(adapter, ctx.body);
+      }
+    );
+    const deleteFolderEndpoint = createEndpoint(
+      "/media/folders/:id",
+      {
+        method: "DELETE"
+      },
+      async (ctx) => {
+        const folder = await getFolderById(adapter, ctx.params.id);
+        if (!folder) {
+          throw ctx.error(404, { message: "Folder not found" });
+        }
+        const context = {
+          params: ctx.params,
+          headers: ctx.headers
+        };
+        if (hooks?.onBeforeDeleteFolder) {
+          await runHookWithShim(
+            () => hooks.onBeforeDeleteFolder(folder, context),
+            ctx.error,
+            "Unauthorized: Cannot delete folder"
+          );
+        }
+        try {
+          await deleteFolder(adapter, ctx.params.id);
+        } catch (err) {
+          throw ctx.error(409, {
+            message: err instanceof Error ? err.message : "Cannot delete folder"
+          });
+        }
+        return { success: true };
+      }
+    );
+    const uploadDirectEndpoint = createEndpoint(
+      "/media/upload",
+      {
+        method: "POST",
+        metadata: {
+          // Tell Better Call this endpoint accepts multipart/form-data so it
+          // parses the body into a FormData object and exposes it as ctx.body.
+          // Without this, Better Call may pre-read the body stream and calling
+          // ctx.request.formData() afterwards fails with "Body already read".
+          allowedMediaTypes: ["multipart/form-data"]
+        }
+      },
+      async (ctx) => {
+        if (!isDirectAdapter(storageAdapter)) {
+          throw ctx.error(400, {
+            message: "Direct upload is only supported with the local storage adapter"
+          });
+        }
+        const body = ctx.body;
+        if (!body || typeof body !== "object") {
+          throw ctx.error(400, {
+            message: "Expected multipart/form-data request body"
+          });
+        }
+        const fileRaw = body.file;
+        if (!fileRaw || typeof fileRaw !== "object" || typeof fileRaw.arrayBuffer !== "function") {
+          throw ctx.error(400, {
+            message: "Missing 'file' field in form data"
+          });
+        }
+        if (typeof fileRaw.size !== "number" || fileRaw.size < 0) {
+          throw ctx.error(400, {
+            message: "File 'size' is missing or invalid"
+          });
+        }
+        if (typeof fileRaw.name !== "string" || !fileRaw.name) {
+          throw ctx.error(400, {
+            message: "File 'name' is missing or invalid"
+          });
+        }
+        if (typeof fileRaw.type !== "string") {
+          throw ctx.error(400, {
+            message: "File 'type' is missing or invalid"
+          });
+        }
+        const file = fileRaw;
+        const context = { headers: ctx.headers };
+        if (hooks?.onBeforeUpload) {
+          await runHookWithShim(
+            () => hooks.onBeforeUpload(
+              {
+                filename: file.name,
+                mimeType: file.type,
+                size: file.size
+              },
+              context
+            ),
+            ctx.error,
+            "Unauthorized: Cannot upload asset"
+          );
+        }
+        validateMimeType(file.type, ctx);
+        if (file.size > maxFileSizeBytes) {
+          throw ctx.error(413, {
+            message: `File size ${file.size} bytes exceeds the limit of ${maxFileSizeBytes} bytes`
+          });
+        }
+        const buffer = Buffer.from(await file.arrayBuffer());
+        const folderId = typeof body.folderId === "string" && body.folderId ? body.folderId : void 0;
+        if (folderId) {
+          const folder = await getFolderById(adapter, folderId);
+          if (!folder) {
+            throw ctx.error(404, { message: "Folder not found" });
+          }
+        }
+        const { url } = await storageAdapter.upload(buffer, {
+          filename: file.name,
+          mimeType: file.type,
+          size: file.size,
+          folderId
+        });
+        let asset;
+        try {
+          asset = await createAsset(adapter, {
+            filename: url.split("/").pop() ?? file.name,
+            originalName: file.name,
+            mimeType: file.type,
+            size: file.size,
+            url,
+            folderId
+          });
+        } catch (err) {
+          try {
+            await storageAdapter.delete(url);
+          } catch (cleanupErr) {
+            console.error(
+              `[btst/media] Failed to clean up orphaned storage file after DB error: ${url}`,
+              cleanupErr
+            );
+          }
+          throw err;
+        }
+        if (hooks?.onAfterUpload) {
+          await hooks.onAfterUpload(asset, context);
+        }
+        return asset;
+      }
+    );
+    const uploadTokenEndpoint = createEndpoint(
+      "/media/upload/token",
+      {
+        method: "POST",
+        body: uploadTokenRequestSchema
+      },
+      async (ctx) => {
+        if (!isS3Adapter(storageAdapter)) {
+          throw ctx.error(400, {
+            message: "Upload token endpoint is only supported with the S3 storage adapter"
+          });
+        }
+        const context = {
+          body: ctx.body,
+          headers: ctx.headers
+        };
+        if (hooks?.onBeforeUpload) {
+          await runHookWithShim(
+            () => hooks.onBeforeUpload(
+              {
+                filename: ctx.body.filename,
+                mimeType: ctx.body.mimeType,
+                size: ctx.body.size
+              },
+              context
+            ),
+            ctx.error,
+            "Unauthorized: Cannot upload asset"
+          );
+        }
+        validateMimeType(ctx.body.mimeType, ctx);
+        if (ctx.body.size > maxFileSizeBytes) {
+          throw ctx.error(413, {
+            message: `File size ${ctx.body.size} bytes exceeds the limit of ${maxFileSizeBytes} bytes`
+          });
+        }
+        let folderId = ctx.body.folderId;
+        if (folderId) {
+          const folder = await getFolderById(adapter, folderId);
+          if (!folder) {
+            throw ctx.error(404, {
+              message: "Folder not found"
+            });
+          }
+          folderId = folder.id;
+        }
+        const filename = sanitizeS3KeySegment(ctx.body.filename);
+        return storageAdapter.generateUploadToken({
+          filename,
+          mimeType: ctx.body.mimeType,
+          size: ctx.body.size,
+          folderId
+        });
+      }
+    );
+    const uploadVercelBlobEndpoint = createEndpoint(
+      "/media/upload/vercel-blob",
+      {
+        method: "POST"
+      },
+      async (ctx) => {
+        if (!isVercelBlobAdapter(storageAdapter)) {
+          throw ctx.error(400, {
+            message: "Vercel Blob endpoint is only supported with the vercelBlobAdapter"
+          });
+        }
+        const context = { headers: ctx.headers };
+        if (!ctx.request) {
+          throw ctx.error(400, {
+            message: "Request object is not available"
+          });
+        }
+        return storageAdapter.handleRequest(ctx.request, {
+          onBeforeGenerateToken: async (pathname, clientPayload) => {
+            const filename = pathname.split("/").pop() ?? pathname;
+            let parsed = {};
+            try {
+              parsed = clientPayload ? JSON.parse(clientPayload) : {};
+            } catch {
+            }
+            const mimeType = parsed.mimeType ?? "application/octet-stream";
+            const size = parsed.size;
+            if (hooks?.onBeforeUpload) {
+              await runHookWithShim(
+                () => hooks.onBeforeUpload(
+                  { filename, mimeType, size },
+                  context
+                ),
+                ctx.error,
+                "Unauthorized: Cannot upload asset"
+              );
+            }
+            validateMimeType(mimeType, ctx);
+            if (size != null && size > maxFileSizeBytes) {
+              throw ctx.error(413, {
+                message: `File size ${size} bytes exceeds the limit of ${maxFileSizeBytes} bytes`
+              });
+            }
+            return {
+              addRandomSuffix: true,
+              allowedContentTypes: allowedMimeTypes && allowedMimeTypes.length > 0 ? allowedMimeTypes : void 0,
+              maximumSizeInBytes: maxFileSizeBytes
+            };
+          }
+        });
+      }
+    );
+    return {
+      listAssets: listAssetsEndpoint,
+      createAsset: createAssetEndpoint,
+      updateAsset: updateAssetEndpoint,
+      deleteAsset: deleteAssetEndpoint,
+      listFolders: listFoldersEndpoint,
+      createFolder: createFolderEndpoint,
+      deleteFolder: deleteFolderEndpoint,
+      uploadDirect: uploadDirectEndpoint,
+      uploadToken: uploadTokenEndpoint,
+      uploadVercelBlob: uploadVercelBlobEndpoint
+    };
+  }
+});
+
+export { mediaBackendPlugin };

package/dist/packages/stack/src/plugins/media/api/query-key-defs.cjs

@@ -0,0 +1,19 @@
+'use strict';
+
+function assetListDiscriminator(params) {
+  return {
+    folderId: params?.folderId,
+    mimeType: params?.mimeType,
+    query: params?.query,
+    limit: params?.limit,
+    offset: params?.offset
+  };
+}
+const MEDIA_QUERY_KEYS = {
+  assetsList: (params) => ["media", "assets", "list", assetListDiscriminator(params)],
+  assetDetail: (id) => ["media", "assets", "detail", id],
+  foldersList: (parentId) => ["media", "folders", "list", parentId ?? "root"]
+};
+
+exports.MEDIA_QUERY_KEYS = MEDIA_QUERY_KEYS;
+exports.assetListDiscriminator = assetListDiscriminator;

package/dist/packages/stack/src/plugins/media/api/query-key-defs.mjs

@@ -0,0 +1,16 @@
+function assetListDiscriminator(params) {
+  return {
+    folderId: params?.folderId,
+    mimeType: params?.mimeType,
+    query: params?.query,
+    limit: params?.limit,
+    offset: params?.offset
+  };
+}
+const MEDIA_QUERY_KEYS = {
+  assetsList: (params) => ["media", "assets", "list", assetListDiscriminator(params)],
+  assetDetail: (id) => ["media", "assets", "detail", id],
+  foldersList: (parentId) => ["media", "folders", "list", parentId ?? "root"]
+};
+
+export { MEDIA_QUERY_KEYS, assetListDiscriminator };

package/dist/packages/stack/src/plugins/media/api/serializers.cjs

@@ -0,0 +1,17 @@
+'use strict';
+
+function serializeAsset(asset) {
+  return {
+    ...asset,
+    createdAt: asset.createdAt.toISOString()
+  };
+}
+function serializeFolder(folder) {
+  return {
+    ...folder,
+    createdAt: folder.createdAt.toISOString()
+  };
+}
+
+exports.serializeAsset = serializeAsset;
+exports.serializeFolder = serializeFolder;

package/dist/packages/stack/src/plugins/media/api/serializers.mjs

@@ -0,0 +1,14 @@
+function serializeAsset(asset) {
+  return {
+    ...asset,
+    createdAt: asset.createdAt.toISOString()
+  };
+}
+function serializeFolder(folder) {
+  return {
+    ...folder,
+    createdAt: folder.createdAt.toISOString()
+  };
+}
+
+export { serializeAsset, serializeFolder };

package/dist/packages/stack/src/plugins/media/api/storage-adapter.cjs

@@ -0,0 +1,15 @@
+'use strict';
+
+function isDirectAdapter(adapter) {
+  return adapter.type === "local";
+}
+function isS3Adapter(adapter) {
+  return adapter.type === "s3";
+}
+function isVercelBlobAdapter(adapter) {
+  return adapter.type === "vercel-blob";
+}
+
+exports.isDirectAdapter = isDirectAdapter;
+exports.isS3Adapter = isS3Adapter;
+exports.isVercelBlobAdapter = isVercelBlobAdapter;

package/dist/packages/stack/src/plugins/media/api/storage-adapter.mjs

@@ -0,0 +1,11 @@
+function isDirectAdapter(adapter) {
+  return adapter.type === "local";
+}
+function isS3Adapter(adapter) {
+  return adapter.type === "s3";
+}
+function isVercelBlobAdapter(adapter) {
+  return adapter.type === "vercel-blob";
+}
+
+export { isDirectAdapter, isS3Adapter, isVercelBlobAdapter };