@btst/stack 3.0.0-rc.1 → 3.0.0-rc.3

package/dist/packages/stack/src/plugins/media/client/upload.mjs

@@ -1,4 +1,6 @@
 "use client";
+import { normalizePath } from '@btst/stack/client';
+import { resolveMediaAsset } from '../asset-url.mjs';
 import { compressImage } from './utils/image-compression.mjs';
 
 const DEFAULT_IMAGE_COMPRESSION = {
@@ -6,11 +8,25 @@ const DEFAULT_IMAGE_COMPRESSION = {
   maxHeight: 2048,
   quality: 0.85
 };
+function createMediaUploadConfig(runtime, overrides = {}) {
+  return {
+    apiBaseURL: runtime.api.baseURL,
+    apiBasePath: runtime.api.basePath,
+    headers: runtime.api.browserHeaders,
+    credentials: runtime.api.credentials,
+    uploadMode: runtime.config?.uploadMode ?? "direct",
+    ...overrides
+  };
+}
+function createMediaApiURL(apiBaseURL, apiBasePath, path) {
+  return `${apiBaseURL}${normalizePath([apiBasePath, path].join("/"))}`;
+}
 async function uploadAsset(config, input) {
   const {
     apiBaseURL,
     apiBasePath,
     headers,
+    credentials,
     uploadMode = "direct",
     imageCompression
   } = config;
@@ -19,37 +35,44 @@ async function uploadAsset(config, input) {
     file,
     imageCompression ?? DEFAULT_IMAGE_COMPRESSION
   );
-  const base = `${apiBaseURL}${apiBasePath}`;
   const headersObj = new Headers(headers);
   if (uploadMode === "direct") {
     const formData = new FormData();
     formData.append("file", processedFile);
     if (folderId) formData.append("folderId", folderId);
-    const res = await fetch(`${base}/media/upload`, {
-      method: "POST",
-      headers: headersObj,
-      body: formData
-    });
+    const res = await fetch(
+      createMediaApiURL(apiBaseURL, apiBasePath, "/media/upload"),
+      {
+        method: "POST",
+        headers: headersObj,
+        credentials,
+        body: formData
+      }
+    );
     if (!res.ok) {
       const err = await res.json().catch(() => ({ message: res.statusText }));
       throw new Error(err.message ?? "Upload failed");
     }
-    return res.json();
+    return resolveMediaAsset(await res.json(), apiBaseURL);
   }
   if (uploadMode === "s3") {
-    const tokenRes = await fetch(`${base}/media/upload/token`, {
-      method: "POST",
-      headers: {
-        ...Object.fromEntries(headersObj.entries()),
-        "Content-Type": "application/json"
-      },
-      body: JSON.stringify({
-        filename: processedFile.name,
-        mimeType: processedFile.type,
-        size: processedFile.size,
-        folderId
-      })
-    });
+    const tokenRes = await fetch(
+      createMediaApiURL(apiBaseURL, apiBasePath, "/media/upload/token"),
+      {
+        method: "POST",
+        headers: {
+          ...Object.fromEntries(headersObj.entries()),
+          "Content-Type": "application/json"
+        },
+        credentials,
+        body: JSON.stringify({
+          filename: processedFile.name,
+          mimeType: processedFile.type,
+          size: processedFile.size,
+          folderId
+        })
+      }
+    );
     if (!tokenRes.ok) {
       const err = await tokenRes.json().catch(() => ({ message: tokenRes.statusText }));
       throw new Error(err.message ?? "Failed to get upload token");
@@ -61,59 +84,104 @@ async function uploadAsset(config, input) {
       body: processedFile
     });
     if (!putRes.ok) throw new Error("Failed to upload to S3");
-    const assetRes = await fetch(`${base}/media/assets`, {
-      method: "POST",
-      headers: {
-        ...Object.fromEntries(headersObj.entries()),
-        "Content-Type": "application/json"
-      },
-      body: JSON.stringify({
-        filename: processedFile.name,
-        originalName: file.name,
-        mimeType: processedFile.type,
-        size: processedFile.size,
-        url: token.payload.publicUrl,
-        folderId
-      })
-    });
+    const assetRes = await fetch(
+      createMediaApiURL(apiBaseURL, apiBasePath, "/media/assets"),
+      {
+        method: "POST",
+        headers: {
+          ...Object.fromEntries(headersObj.entries()),
+          "Content-Type": "application/json"
+        },
+        credentials,
+        body: JSON.stringify({
+          filename: processedFile.name,
+          originalName: file.name,
+          mimeType: processedFile.type,
+          size: processedFile.size,
+          url: token.payload.publicUrl,
+          folderId
+        })
+      }
+    );
     if (!assetRes.ok) {
       const err = await assetRes.json().catch(() => ({ message: assetRes.statusText }));
       throw new Error(err.message ?? "Failed to register asset");
     }
-    return assetRes.json();
+    return resolveMediaAsset(
+      await assetRes.json(),
+      apiBaseURL
+    );
   }
   if (uploadMode === "vercel-blob") {
-    const { upload } = await import('@vercel/blob/client');
-    const blob = await upload(processedFile.name, processedFile, {
-      access: "public",
-      handleUploadUrl: `${base}/media/upload/vercel-blob`,
-      clientPayload: JSON.stringify({
-        mimeType: processedFile.type,
-        size: processedFile.size
-      })
+    const handleUploadUrl = createMediaApiURL(
+      apiBaseURL,
+      apiBasePath,
+      "/media/upload/vercel-blob"
+    );
+    const clientPayload = JSON.stringify({
+      mimeType: processedFile.type,
+      size: processedFile.size,
+      ...folderId ? { folderId } : {}
     });
-    const assetRes = await fetch(`${base}/media/assets`, {
+    const tokenRes = await fetch(handleUploadUrl, {
       method: "POST",
       headers: {
         ...Object.fromEntries(headersObj.entries()),
         "Content-Type": "application/json"
       },
+      credentials,
       body: JSON.stringify({
-        filename: processedFile.name,
-        originalName: file.name,
-        mimeType: processedFile.type,
-        size: processedFile.size,
-        url: blob.url,
-        folderId
+        type: "blob.generate-client-token",
+        payload: {
+          pathname: processedFile.name,
+          callbackUrl: handleUploadUrl,
+          clientPayload,
+          multipart: false
+        }
       })
     });
+    if (!tokenRes.ok) {
+      const err = await tokenRes.json().catch(() => ({ message: tokenRes.statusText }));
+      throw new Error(err.message ?? "Failed to get Vercel Blob upload token");
+    }
+    const { clientToken } = await tokenRes.json();
+    if (!clientToken) {
+      throw new Error("Failed to get Vercel Blob upload token");
+    }
+    const { put } = await import('@vercel/blob/client');
+    const blob = await put(processedFile.name, processedFile, {
+      access: "public",
+      token: clientToken
+    });
+    const assetRes = await fetch(
+      createMediaApiURL(apiBaseURL, apiBasePath, "/media/assets"),
+      {
+        method: "POST",
+        headers: {
+          ...Object.fromEntries(headersObj.entries()),
+          "Content-Type": "application/json"
+        },
+        credentials,
+        body: JSON.stringify({
+          filename: processedFile.name,
+          originalName: file.name,
+          mimeType: processedFile.type,
+          size: processedFile.size,
+          url: blob.url,
+          folderId
+        })
+      }
+    );
     if (!assetRes.ok) {
       const err = await assetRes.json().catch(() => ({ message: assetRes.statusText }));
       throw new Error(err.message ?? "Failed to register asset");
     }
-    return assetRes.json();
+    return resolveMediaAsset(
+      await assetRes.json(),
+      apiBaseURL
+    );
   }
   throw new Error(`Unknown uploadMode: ${uploadMode}`);
 }
 
-export { uploadAsset };
+export { createMediaUploadConfig, uploadAsset };

package/dist/packages/stack/src/plugins/media/db.cjs

@@ -45,6 +45,10 @@ const mediaSchema = db.createDbPlugin("media", {
       createdAt: {
         type: "date",
         defaultValue: () => /* @__PURE__ */ new Date()
+      },
+      updatedAt: {
+        type: "date",
+        defaultValue: () => /* @__PURE__ */ new Date()
       }
     }
   },
@@ -70,6 +74,10 @@ const mediaSchema = db.createDbPlugin("media", {
       createdAt: {
         type: "date",
         defaultValue: () => /* @__PURE__ */ new Date()
+      },
+      updatedAt: {
+        type: "date",
+        defaultValue: () => /* @__PURE__ */ new Date()
       }
     }
   }

package/dist/packages/stack/src/plugins/media/db.mjs

@@ -43,6 +43,10 @@ const mediaSchema = createDbPlugin("media", {
       createdAt: {
         type: "date",
         defaultValue: () => /* @__PURE__ */ new Date()
+      },
+      updatedAt: {
+        type: "date",
+        defaultValue: () => /* @__PURE__ */ new Date()
       }
     }
   },
@@ -68,6 +72,10 @@ const mediaSchema = createDbPlugin("media", {
       createdAt: {
         type: "date",
         defaultValue: () => /* @__PURE__ */ new Date()
+      },
+      updatedAt: {
+        type: "date",
+        defaultValue: () => /* @__PURE__ */ new Date()
       }
     }
   }

package/dist/packages/stack/src/plugins/open-api/api/generator.cjs

@@ -16,6 +16,9 @@ function _interopNamespaceCompat(e) {
 
 const z__namespace = /*#__PURE__*/_interopNamespaceCompat(z);
 
+function compareStable(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
 function toOpenApiPath(path) {
   return path.split("/").map((part) => part.startsWith(":") ? `{${part.slice(1)}}` : part).join("/");
 }
@@ -218,17 +221,28 @@ function getErrorResponses() {
 function generateOpenAPISchema(context, options) {
   const paths = {};
   const tags = [];
-  for (const [pluginKey, plugin] of Object.entries(context.plugins)) {
-    if (pluginKey === "openApi" || plugin.name === "open-api") {
+  const inventory = new Map(
+    (context.endpointInventory ?? []).map((entry) => [
+      `${entry.pluginKey}\0${entry.routeKey}`,
+      entry
+    ])
+  );
+  for (const [pluginKey, plugin] of Object.entries(context.plugins).sort(
+    ([left], [right]) => compareStable(left, right)
+  )) {
+    const pluginId = plugin.id;
+    if (pluginId === "openApi") {
       continue;
     }
-    const pluginRoutes = plugin.routes(context.adapter, context);
+    const pluginRoutes = context.pluginRoutes[pluginKey] ?? {};
     const tagName = pluginKey.charAt(0).toUpperCase() + pluginKey.slice(1);
     tags.push({
       name: tagName,
       description: `${tagName} plugin endpoints`
     });
-    for (const [routeKey, endpoint] of Object.entries(pluginRoutes)) {
+    for (const [routeKey, endpoint] of Object.entries(pluginRoutes).sort(
+      ([left], [right]) => compareStable(left, right)
+    )) {
       const ep = endpoint;
       const path = ep.path;
       const endpointOptions = ep.options || {};
@@ -256,6 +270,13 @@ function generateOpenAPISchema(context, options) {
           ...getErrorResponses()
         }
       };
+      const declaration = inventory.get(`${pluginKey}\0${routeKey}`);
+      if (declaration) {
+        operation["x-btst-access"] = declaration.access;
+        if (declaration.permissionId) {
+          operation["x-btst-permission"] = declaration.permissionId;
+        }
+      }
       if (["post", "put", "patch"].includes(method)) {
         const requestBody = getRequestBody(endpointOptions);
         if (requestBody) {
@@ -265,6 +286,16 @@ function generateOpenAPISchema(context, options) {
       paths[openApiPath][method] = operation;
     }
   }
+  const deterministicPaths = Object.fromEntries(
+    Object.entries(paths).sort(([left], [right]) => compareStable(left, right)).map(([path, methods]) => [
+      path,
+      Object.fromEntries(
+        Object.entries(methods).sort(
+          ([left], [right]) => compareStable(left, right)
+        )
+      )
+    ])
+  );
   return {
     openapi: "3.1.0",
     info: {
@@ -279,7 +310,7 @@ function generateOpenAPISchema(context, options) {
       }
     ],
     tags,
-    paths,
+    paths: deterministicPaths,
     components: {
       securitySchemes: {
         bearerAuth: {

package/dist/packages/stack/src/plugins/open-api/api/generator.mjs

@@ -1,5 +1,8 @@
 import * as z from 'zod';
 
+function compareStable(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
 function toOpenApiPath(path) {
   return path.split("/").map((part) => part.startsWith(":") ? `{${part.slice(1)}}` : part).join("/");
 }
@@ -202,17 +205,28 @@ function getErrorResponses() {
 function generateOpenAPISchema(context, options) {
   const paths = {};
   const tags = [];
-  for (const [pluginKey, plugin] of Object.entries(context.plugins)) {
-    if (pluginKey === "openApi" || plugin.name === "open-api") {
+  const inventory = new Map(
+    (context.endpointInventory ?? []).map((entry) => [
+      `${entry.pluginKey}\0${entry.routeKey}`,
+      entry
+    ])
+  );
+  for (const [pluginKey, plugin] of Object.entries(context.plugins).sort(
+    ([left], [right]) => compareStable(left, right)
+  )) {
+    const pluginId = plugin.id;
+    if (pluginId === "openApi") {
       continue;
     }
-    const pluginRoutes = plugin.routes(context.adapter, context);
+    const pluginRoutes = context.pluginRoutes[pluginKey] ?? {};
     const tagName = pluginKey.charAt(0).toUpperCase() + pluginKey.slice(1);
     tags.push({
       name: tagName,
       description: `${tagName} plugin endpoints`
     });
-    for (const [routeKey, endpoint] of Object.entries(pluginRoutes)) {
+    for (const [routeKey, endpoint] of Object.entries(pluginRoutes).sort(
+      ([left], [right]) => compareStable(left, right)
+    )) {
       const ep = endpoint;
       const path = ep.path;
       const endpointOptions = ep.options || {};
@@ -240,6 +254,13 @@ function generateOpenAPISchema(context, options) {
           ...getErrorResponses()
         }
       };
+      const declaration = inventory.get(`${pluginKey}\0${routeKey}`);
+      if (declaration) {
+        operation["x-btst-access"] = declaration.access;
+        if (declaration.permissionId) {
+          operation["x-btst-permission"] = declaration.permissionId;
+        }
+      }
       if (["post", "put", "patch"].includes(method)) {
         const requestBody = getRequestBody(endpointOptions);
         if (requestBody) {
@@ -249,6 +270,16 @@ function generateOpenAPISchema(context, options) {
       paths[openApiPath][method] = operation;
     }
   }
+  const deterministicPaths = Object.fromEntries(
+    Object.entries(paths).sort(([left], [right]) => compareStable(left, right)).map(([path, methods]) => [
+      path,
+      Object.fromEntries(
+        Object.entries(methods).sort(
+          ([left], [right]) => compareStable(left, right)
+        )
+      )
+    ])
+  );
   return {
     openapi: "3.1.0",
     info: {
@@ -263,7 +294,7 @@ function generateOpenAPISchema(context, options) {
       }
     ],
     tags,
-    paths,
+    paths: deterministicPaths,
     components: {
       securitySchemes: {
         bearerAuth: {

package/dist/packages/stack/src/plugins/open-api/api/plugin.cjs

@@ -5,6 +5,16 @@ const db = require('../db.cjs');
 const generator = require('./generator.cjs');
 const logo = require('../logo.cjs');
 
+const OPEN_API_INFRASTRUCTURE_ROUTES = Object.freeze({
+  generateSchema: Object.freeze({
+    access: "public",
+    rationale: "Serves deterministic API metadata and does not execute an application business operation."
+  }),
+  reference: Object.freeze({
+    access: "public",
+    rationale: "Serves the documentation UI for the same public schema without executing an application business operation."
+  })
+});
 function escapeHtml(str) {
   return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
@@ -46,12 +56,13 @@ function getScalarHTML(schema, theme = "default", nonce) {
   </body>
 </html>`;
 }
-const openApiBackendPlugin = (options) => {
-  const referencePath = options?.path ?? "/reference";
+const openApiBackendPlugin = (options = {}) => {
+  const referencePath = options.path ?? "/reference";
   let storedContext = null;
   return api.defineBackendPlugin({
-    name: "open-api",
+    id: "openApi",
     dbPlugin: db.openApiSchema,
+    infrastructureRoutes: OPEN_API_INFRASTRUCTURE_ROUTES,
     routes: (_adapter, context) => {
       storedContext = context ?? null;
       const generateSchema = api.createEndpoint(
@@ -66,9 +77,9 @@ const openApiBackendPlugin = (options) => {
             });
           }
           const schema = generator.generateOpenAPISchema(storedContext, {
-            title: options?.title,
-            description: options?.description,
-            version: options?.version
+            title: options.title,
+            description: options.description,
+            version: options.version
           });
           return schema;
         }
@@ -79,7 +90,7 @@ const openApiBackendPlugin = (options) => {
           method: "GET"
         },
         async (ctx) => {
-          if (options?.disableDefaultReference) {
+          if (options.disableDefaultReference) {
             throw ctx.error(404, {
               message: "Reference page is disabled"
             });
@@ -90,12 +101,12 @@ const openApiBackendPlugin = (options) => {
             });
           }
           const schema = generator.generateOpenAPISchema(storedContext, {
-            title: options?.title,
-            description: options?.description,
-            version: options?.version
+            title: options.title,
+            description: options.description,
+            version: options.version
           });
           return new Response(
-            getScalarHTML(schema, options?.theme, options?.nonce),
+            getScalarHTML(schema, options.theme, options.nonce),
             {
               headers: {
                 "Content-Type": "text/html; charset=utf-8"

package/dist/packages/stack/src/plugins/open-api/api/plugin.mjs

@@ -3,6 +3,16 @@ import { openApiSchema } from '../db.mjs';
 import { generateOpenAPISchema } from './generator.mjs';
 import { logo } from '../logo.mjs';
 
+const OPEN_API_INFRASTRUCTURE_ROUTES = Object.freeze({
+  generateSchema: Object.freeze({
+    access: "public",
+    rationale: "Serves deterministic API metadata and does not execute an application business operation."
+  }),
+  reference: Object.freeze({
+    access: "public",
+    rationale: "Serves the documentation UI for the same public schema without executing an application business operation."
+  })
+});
 function escapeHtml(str) {
   return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 }
@@ -44,12 +54,13 @@ function getScalarHTML(schema, theme = "default", nonce) {
   </body>
 </html>`;
 }
-const openApiBackendPlugin = (options) => {
-  const referencePath = options?.path ?? "/reference";
+const openApiBackendPlugin = (options = {}) => {
+  const referencePath = options.path ?? "/reference";
   let storedContext = null;
   return defineBackendPlugin({
-    name: "open-api",
+    id: "openApi",
     dbPlugin: openApiSchema,
+    infrastructureRoutes: OPEN_API_INFRASTRUCTURE_ROUTES,
     routes: (_adapter, context) => {
       storedContext = context ?? null;
       const generateSchema = createEndpoint(
@@ -64,9 +75,9 @@ const openApiBackendPlugin = (options) => {
             });
           }
           const schema = generateOpenAPISchema(storedContext, {
-            title: options?.title,
-            description: options?.description,
-            version: options?.version
+            title: options.title,
+            description: options.description,
+            version: options.version
           });
           return schema;
         }
@@ -77,7 +88,7 @@ const openApiBackendPlugin = (options) => {
           method: "GET"
         },
         async (ctx) => {
-          if (options?.disableDefaultReference) {
+          if (options.disableDefaultReference) {
             throw ctx.error(404, {
               message: "Reference page is disabled"
             });
@@ -88,12 +99,12 @@ const openApiBackendPlugin = (options) => {
             });
           }
           const schema = generateOpenAPISchema(storedContext, {
-            title: options?.title,
-            description: options?.description,
-            version: options?.version
+            title: options.title,
+            description: options.description,
+            version: options.version
           });
           return new Response(
-            getScalarHTML(schema, options?.theme, options?.nonce),
+            getScalarHTML(schema, options.theme, options.nonce),
             {
               headers: {
                 "Content-Type": "text/html; charset=utf-8"