@decocms/blocks-admin 7.0.0

package/src/admin/setup.ts

@@ -0,0 +1,85 @@
+/**
+ * Client-safe admin setup functions.
+ *
+ * These functions only set module-level state (no node: imports,
+ * no AsyncLocalStorage). Safe to import in both client and SSR builds.
+ *
+ * For server-only handlers (handleMeta, handleRender, etc.),
+ * import from "@decocms/start/admin" instead.
+ */
+
+export {
+  type InvokeAction,
+  type InvokeLoader,
+  registerInvokeHandlers,
+  setInvokeActions,
+  setInvokeLoaders,
+} from "./invoke";
+export { setMetaData } from "./meta";
+export {
+  type ActionConfig,
+  type LoaderConfig,
+  type MatcherConfig,
+  registerActionSchema,
+  registerActionSchemas,
+  registerLoaderSchema,
+  registerLoaderSchemas,
+  registerMatcherSchema,
+  registerMatcherSchemas,
+} from "@decocms/blocks/cms";
+
+let cssHref: string | null = null;
+let fontHrefs: string[] = [];
+let themeName = "";
+let bodyClass = "";
+let htmlLang = "en";
+
+/**
+ * Optional React component that wraps section renders in admin previews.
+ * Use this to provide context that sections depend on (Router, QueryClient, etc.)
+ * without which renderToString would crash.
+ *
+ * The wrapper receives `{ children }` and should render them inside the
+ * necessary providers.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let previewWrapperComponent: any = null;
+
+/**
+ * Register a wrapper component for admin preview renders.
+ *
+ * @example
+ * ```ts
+ * // In site's setup.ts:
+ * import { setPreviewWrapper } from "@decocms/start/admin/setup";
+ * import { PreviewProviders } from "./components/PreviewProviders";
+ * setPreviewWrapper(PreviewProviders);
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function setPreviewWrapper(wrapper: any) {
+  previewWrapperComponent = wrapper;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function getPreviewWrapper(): any {
+  return previewWrapperComponent;
+}
+
+export function setRenderShell(opts: {
+  css?: string;
+  fonts?: string[];
+  theme?: string;
+  bodyClass?: string;
+  lang?: string;
+}) {
+  if (opts.css) cssHref = opts.css;
+  if (opts.fonts) fontHrefs = opts.fonts;
+  if (opts.theme !== undefined) themeName = opts.theme;
+  if (opts.bodyClass !== undefined) bodyClass = opts.bodyClass;
+  if (opts.lang !== undefined) htmlLang = opts.lang;
+}
+
+export function getRenderShellConfig() {
+  return { cssHref, fontHrefs, themeName, bodyClass, htmlLang };
+}

package/src/apps/autoconfig.ts

@@ -0,0 +1,135 @@
+/**
+ * Registry-driven auto-configuration of known apps from CMS blocks.
+ *
+ * A site passes an `AppRegistry` (declarative list of known app blockKeys +
+ * lazy module imports). For every registry entry whose `blockKey` exists in
+ * the decofile, this calls `mod.configure(block, resolveSecret)` and then
+ * hands the resulting AppDefinitions off to `setupApps()`.
+ *
+ * The canonical registry lives in `@decocms/apps/registry` so the framework
+ * itself has zero knowledge of which apps exist.
+ *
+ * Usage in setup.ts:
+ *   import { autoconfigApps } from "@decocms/start/apps/autoconfig";
+ *   import { APP_REGISTRY } from "@decocms/apps/registry";
+ *   await autoconfigApps(generatedBlocks, APP_REGISTRY);
+ */
+
+import { onChange } from "@decocms/blocks/cms";
+import { resolveSecret } from "@decocms/blocks/sdk/crypto";
+import {
+  setupApps,
+  type AppDefinition,
+  type AppDefinitionWithHandlers,
+} from "../sdk/setupApps";
+
+/**
+ * Shape of the secret resolver passed to each app's `configure()`. Matches
+ * `resolveSecret` in `src/sdk/crypto.ts`. Apps typically narrow the return
+ * type inside their own `configure()` by throwing on null.
+ */
+export type ResolveSecret = (
+  value: unknown,
+  envVarName?: string,
+) => Promise<string | null>;
+
+/**
+ * One entry in the app registry — describes a single installable app.
+ * Sites pass an array of these to `autoconfigApps()` (typically imported
+ * from `@decocms/apps/registry`).
+ */
+export interface AppRegistryEntry {
+  /** Block key in the decofile, e.g. "deco-shopify". */
+  blockKey: string;
+
+  /**
+   * Lazy import of the app's mod module. Must return an object exposing
+   * `configure(block, resolveSecret)` and optionally `handlers`.
+   *
+   * Use a string-literal dynamic import so bundlers (Vite/Rollup) can
+   * statically trace the chunk. E.g.
+   *   () => import("@decocms/apps/shopify/mod")
+   */
+  module: () => Promise<{
+    configure: (
+      block: unknown,
+      resolveSecret: ResolveSecret,
+    ) => Promise<AppDefinition | null>;
+    handlers?: Record<string, (props: any, req: Request) => Promise<any>>;
+  }>;
+
+  /** Human-readable name shown in admin install UI. */
+  displayName?: string;
+  /** Icon URL (absolute or site-relative) shown in admin install UI. */
+  icon?: string;
+  /** Grouping label, e.g. "commerce", "email", "analytics". */
+  category?: string;
+  /** Short summary (one sentence) shown in admin install UI. */
+  description?: string;
+}
+
+export type AppRegistry = readonly AppRegistryEntry[];
+
+async function configureAllApps(
+  blocks: Record<string, unknown>,
+  registry: AppRegistry,
+): Promise<AppDefinitionWithHandlers[]> {
+  const apps: AppDefinitionWithHandlers[] = [];
+
+  for (const entry of registry) {
+    const block = blocks[entry.blockKey];
+    if (!block) continue;
+
+    try {
+      const mod = await entry.module();
+      if (typeof mod?.configure !== "function") continue;
+
+      const appDef: AppDefinition | null = await mod.configure(
+        block,
+        resolveSecret,
+      );
+      if (!appDef) continue;
+
+      const withHandlers: AppDefinitionWithHandlers = {
+        ...appDef,
+        handlers: mod.handlers,
+      };
+      apps.push(withHandlers);
+    } catch {
+      // App module missing, configure threw, or block was malformed — skip.
+    }
+  }
+
+  return apps;
+}
+
+/**
+ * Auto-configure apps from CMS blocks against a declarative registry.
+ *
+ * Call once in setup.ts after setBlocks(). Re-runs on admin hot-reload.
+ *
+ * @param blocks   Decofile blocks (from blocks.gen or loadBlocks()).
+ * @param registry List of installable apps — typically
+ *                 `import { APP_REGISTRY } from "@decocms/apps/registry"`.
+ */
+export async function autoconfigApps(
+  blocks: Record<string, unknown>,
+  registry: AppRegistry,
+): Promise<void> {
+  if (typeof document !== "undefined") return; // server-only
+  if (!registry || registry.length === 0) return;
+
+  const apps = await configureAllApps(blocks, registry);
+  if (apps.length > 0) {
+    await setupApps(apps);
+  }
+
+  // Re-configure on admin hot-reload
+  onChange(async (newBlocks) => {
+    if (typeof document !== "undefined") return;
+    const updatedApps = await configureAllApps(newBlocks, registry);
+    if (updatedApps.length > 0) {
+      await setupApps(updatedApps);
+    }
+  });
+}

package/src/apps/index.ts

@@ -0,0 +1,24 @@
+/**
+ * Public entry point for app-install primitives.
+ *
+ * Sites import from `@decocms/start/apps`:
+ *   - `autoconfigApps(blocks, registry)` — main bootstrap call
+ *   - `AppRegistry`, `AppRegistryEntry` — registry types
+ *   - `setupApps`, `AppDefinition` — lower-level primitives when composing custom registries
+ */
+
+export {
+  autoconfigApps,
+  type AppRegistry,
+  type AppRegistryEntry,
+} from "./autoconfig";
+
+export {
+  setupApps,
+  registerAppMiddleware,
+  getAppMiddleware,
+  type AppDefinition,
+  type AppDefinitionWithHandlers,
+  type AppManifest,
+  type AppMiddleware,
+} from "../sdk/setupApps";

package/src/createAdminSetup.ts

@@ -0,0 +1,64 @@
+/**
+ * The admin-facing half of a site's one-call bootstrap: admin meta schema,
+ * render shell config, preview wrapper, and commerce-loaders-to-invoke
+ * wiring. Call alongside createSiteSetup() (@decocms/blocks/setup)
+ * — the two were one function before the package split; they're separate
+ * here because these four steps need admin/index.ts's setters, which
+ * runtime cannot import without creating a circular dependency.
+ */
+import {
+  setInvokeLoaders,
+  setMetaData,
+  setPreviewWrapper,
+  setRenderShell,
+} from "./admin/index";
+
+export interface AdminSetupOptions {
+  /**
+   * Lazy loader for admin meta schema — only fetched when admin requests it:
+   * `() => import("./server/admin/meta.gen.json").then(m => m.default)`
+   */
+  meta: () => Promise<any>;
+
+  /** CSS file URL from Vite `?url` import. */
+  css: string;
+
+  /** Font URLs to preload in admin preview shell. */
+  fonts?: string[];
+
+  /** Preview wrapper component for admin preview iframe. */
+  previewWrapper?: React.ComponentType<any>;
+
+  /**
+   * Commerce loaders getter — passed to `setInvokeLoaders`.
+   * Use a thunk so the full map (including site-specific loaders
+   * defined after createAdminSetup) is captured.
+   */
+  getCommerceLoaders?: () => Record<string, (props: any, request?: Request) => Promise<any>>;
+}
+
+/**
+ * Bootstrap a Deco site's admin protocol — meta schema, render shell,
+ * preview wrapper, commerce-loader-to-invoke wiring. Call alongside
+ * createSiteSetup() (@decocms/blocks/setup).
+ */
+export function createAdminSetup(options: AdminSetupOptions): void {
+  // 7. Admin meta schema (lazy)
+  options.meta().then((data) => setMetaData(data));
+
+  // 8. Render shell
+  setRenderShell({
+    css: options.css,
+    fonts: options.fonts,
+  });
+
+  // 9. Preview wrapper
+  if (options.previewWrapper) {
+    setPreviewWrapper(options.previewWrapper);
+  }
+
+  // 10. Commerce loaders → invoke
+  if (options.getCommerceLoaders) {
+    setInvokeLoaders(options.getCommerceLoaders);
+  }
+}

package/src/sdk/htmlShell.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared HTML shell builder for admin preview iframes and render endpoints.
+ *
+ * Both `workerEntry.ts` (preview shell) and `admin/render.ts` (section render)
+ * need to produce an HTML document with the site's CSS, fonts, and theme.
+ * This module provides a single implementation to keep them consistent.
+ */
+
+import { getRenderShellConfig } from "../admin/setup";
+
+export interface HtmlShellOptions {
+  /** Content to inject into <body>. */
+  body?: string;
+  /** Inline <script> content to inject in <head>. */
+  script?: string;
+}
+
+/**
+ * Build a complete HTML shell using the current render config
+ * (set via `setRenderShell()` in the site's setup.ts).
+ */
+export function buildHtmlShell(options: HtmlShellOptions = {}): string {
+  const { cssHref, fontHrefs, themeName, bodyClass, htmlLang } = getRenderShellConfig();
+
+  const themeAttr = themeName ? ` data-theme="${themeName}"` : "";
+  const langAttr = htmlLang ? ` lang="${htmlLang}"` : "";
+  const bodyAttr = bodyClass ? ` class="${bodyClass}"` : "";
+
+  const stylesheets = [
+    ...fontHrefs.map((href) => `<link rel="stylesheet" href="${href}" />`),
+    cssHref ? `<link rel="stylesheet" href="${cssHref}" />` : "",
+  ]
+    .filter(Boolean)
+    .join("\n    ");
+
+  const scriptTag = options.script ? `<script>${options.script}</script>` : "";
+
+  const bodyContent = options.body ?? `<div id="preview-root" style="display:flex;align-items:center;justify-content:center;min-height:100vh;font-family:system-ui;color:#666;">
+        Loading preview...
+    </div>`;
+
+  return `<!DOCTYPE html>
+<html${langAttr}${themeAttr}>
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Preview</title>
+    ${stylesheets}
+    ${scriptTag}
+</head>
+<body${bodyAttr}>
+${bodyContent}
+</body>
+</html>`;
+}

package/src/sdk/setupApps.ts

@@ -0,0 +1,263 @@
+/**
+ * App system integration pipeline.
+ *
+ * Consumes AppDefinition objects from @decocms/apps and automates:
+ * 1. Invoke handler registration (from manifest + explicit handlers)
+ * 2. Section registration (when manifest.sections is available)
+ * 3. App middleware registration (with state injection into RequestContext)
+ *
+ * @example
+ * ```ts
+ * import { setupApps } from "@decocms/start/sdk/setupApps";
+ * import * as vtexApp from "@decocms/apps/vtex/mod";
+ * import * as resendApp from "@decocms/apps/resend/mod";
+ *
+ * const vtex = await vtexApp.configure(blocks["deco-vtex"], resolveSecret);
+ * const resend = await resendApp.configure(blocks["deco-resend"], resolveSecret);
+ *
+ * await setupApps([vtex, resend].filter(Boolean));
+ * ```
+ */
+
+import { clearInvokeHandlers, registerInvokeHandlers } from "../admin/invoke";
+import {
+  registerSections,
+  registerCommerceLoaders,
+  unregisterCommerceLoader,
+} from "@decocms/blocks/cms";
+import { RequestContext } from "@decocms/blocks/sdk/requestContext";
+
+// ---------------------------------------------------------------------------
+// Types — mirrors @decocms/apps/commerce/app-types without importing it
+// ---------------------------------------------------------------------------
+
+export interface AppManifest {
+  name: string;
+  loaders: Record<string, Record<string, unknown>>;
+  actions: Record<string, Record<string, unknown>>;
+  sections?: Record<string, () => Promise<any>>;
+}
+
+export interface AppMiddleware {
+  (request: Request, next: () => Promise<Response>): Promise<Response>;
+}
+
+export interface AppDefinition<TState = unknown> {
+  name: string;
+  manifest: AppManifest;
+  state: TState;
+  middleware?: AppMiddleware;
+  dependencies?: AppDefinition[];
+}
+
+/**
+ * Extended definition with optional explicit handlers.
+ * autoconfigApps() attaches mod.handlers here before calling setupApps().
+ */
+export interface AppDefinitionWithHandlers<TState = unknown>
+  extends AppDefinition<TState> {
+  /** Pre-wrapped handlers from the app's mod.ts (e.g. unwrapped VTEX actions). */
+  handlers?: Record<string, (props: any, request: Request) => Promise<any>>;
+}
+
+// ---------------------------------------------------------------------------
+// App middleware registry
+// ---------------------------------------------------------------------------
+
+/** Per-app state entries — injected into RequestContext.bag on every request. */
+const appStates: Array<{ name: string; state: unknown }> = [];
+
+const appMiddlewares: Array<{
+  name: string;
+  middleware: AppMiddleware;
+}> = [];
+
+/**
+ * Keys this module wrote into the commerce-loaders map. Tracked so hot-reload
+ * can wipe app-owned entries without touching site-local registrations.
+ */
+const appCommerceLoaderKeys = new Set<string>();
+
+function clearAppCommerceLoaders() {
+  for (const key of appCommerceLoaderKeys) unregisterCommerceLoader(key);
+  appCommerceLoaderKeys.clear();
+}
+
+function registerAppState(name: string, state: unknown) {
+  appStates.push({ name, state });
+}
+
+export function registerAppMiddleware(
+  name: string,
+  mw: AppMiddleware,
+) {
+  appMiddlewares.push({ name, middleware: mw });
+}
+
+/**
+ * Clear all registrations. Called before re-running setupApps()
+ * on admin hot-reload to prevent duplicate middleware/state entries.
+ */
+function clearRegistrations() {
+  appStates.length = 0;
+  appMiddlewares.length = 0;
+}
+
+/**
+ * Returns a chained middleware that runs all registered app middlewares.
+ * The site wires this into its own createMiddleware() chain.
+ *
+ * Before running app middlewares, all app states are injected into
+ * RequestContext.bag so loaders can access them via getAppState().
+ *
+ * Returns undefined if no app states or middlewares were registered.
+ */
+export function getAppMiddleware(): AppMiddleware | undefined {
+  if (appStates.length === 0 && appMiddlewares.length === 0) return undefined;
+
+  return async (request, next) => {
+    // Inject all app states into RequestContext bag
+    for (const { name, state } of appStates) {
+      RequestContext.setBag(`app:${name}:state`, state);
+    }
+
+    // Chain app middlewares (first registered runs outermost)
+    if (appMiddlewares.length === 0) return next();
+    const run = async (i: number): Promise<Response> => {
+      if (i >= appMiddlewares.length) return next();
+      return appMiddlewares[i].middleware(request, () => run(i + 1));
+    };
+    return run(0);
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Dependency flattening
+// ---------------------------------------------------------------------------
+
+/**
+ * Topological sort: dependencies before parents.
+ * Combined with first-wins registration in registerInvokeHandlers,
+ * this means parent apps can override handlers from their dependencies
+ * by providing explicit `handlers` (registered before manifest flatten).
+ */
+function flattenDependencies(apps: AppDefinition[]): AppDefinition[] {
+  const seen = new Set<string>();
+  const result: AppDefinition[] = [];
+
+  function visit(app: AppDefinition) {
+    if (seen.has(app.name)) return;
+    seen.add(app.name);
+    if (app.dependencies) {
+      for (const dep of app.dependencies) visit(dep);
+    }
+    result.push(app);
+  }
+
+  for (const app of apps) visit(app);
+  return result;
+}
+
+/**
+ * Register handlers into the commerce-loaders map used by the CMS resolve path
+ * (src/cms/resolve.ts). Tracks the keys so clearAppCommerceLoaders() can revert
+ * them on hot-reload without clobbering site-registered loaders.
+ *
+ * CommerceLoader receives `(props)` only. The admin invoke path passes
+ * `(props, req)`; here `req` is undefined. Handlers that need `req` should
+ * rely on RequestContext instead of a positional argument.
+ */
+function registerAppCommerceHandlers(
+  handlers: Record<string, (props: any, req: Request) => Promise<any>>,
+) {
+  const entries: Record<string, (props: any) => Promise<any>> = {};
+  for (const [key, handler] of Object.entries(handlers)) {
+    entries[key] = (props: any) => handler(props, undefined as unknown as Request);
+    appCommerceLoaderKeys.add(key);
+  }
+  registerCommerceLoaders(entries);
+}
+
+// ---------------------------------------------------------------------------
+// Main pipeline
+// ---------------------------------------------------------------------------
+
+/**
+ * Initialize apps from their AppDefinitions.
+ *
+ * Call once in setup.ts after configuring apps via their mod.configure().
+ * Handles: invoke handler registration, section registration, middleware setup.
+ */
+export async function setupApps(
+  apps: Array<AppDefinitionWithHandlers | AppDefinition>,
+): Promise<void> {
+  if (typeof document !== "undefined") return; // server-only
+
+  // Clear previous registrations (safe for hot-reload via onChange)
+  clearRegistrations();
+  clearInvokeHandlers();
+  clearAppCommerceLoaders();
+
+  for (const app of flattenDependencies(apps as AppDefinition[])) {
+    const appWithHandlers = app as AppDefinitionWithHandlers;
+
+    // 1. Register explicit handlers (pre-unwrapped by the app, e.g. resend)
+    //    These also go into the commerce-loaders map so the CMS resolve path
+    //    (src/cms/resolve.ts) can dispatch to them by __resolveType.
+    if (appWithHandlers.handlers) {
+      registerInvokeHandlers(appWithHandlers.handlers);
+      registerAppCommerceHandlers(appWithHandlers.handlers);
+    }
+
+    // 2. Flatten manifest modules → individual invoke handlers.
+    //
+    //   Convention (mirrors legacy deco-cx/apps):
+    //     - `default` export is registered at the moduleKey itself.
+    //         shopify/loaders/ProductList.ts (default) → key "shopify/loaders/ProductList"
+    //     - Named function exports are registered at `${moduleKey}/${fnName}`.
+    //         vtex/actions/checkout.ts ({ getOrCreateCart, addItemsToCart })
+    //         → keys "vtex/actions/checkout/getOrCreateCart", ".../addItemsToCart"
+    //     - Each key also gets a `.ts` sibling for callers that include the
+    //       extension (admin invoke path, some __resolveType producers).
+    for (const category of ["loaders", "actions"] as const) {
+      const modules = app.manifest[category];
+      if (!modules) continue;
+
+      for (const [moduleKey, moduleExports] of Object.entries(modules)) {
+        const exports = moduleExports as Record<string, unknown>;
+
+        for (const [fnName, fn] of Object.entries(exports)) {
+          if (typeof fn !== "function") continue;
+          const key = fnName === "default"
+            ? moduleKey
+            : `${moduleKey}/${fnName}`;
+          const handler = (props: any, req: Request) =>
+            (fn as Function)(props, req);
+          registerInvokeHandlers({
+            [key]: handler,
+            [`${key}.ts`]: handler,
+          });
+          registerAppCommerceHandlers({
+            [key]: handler,
+            [`${key}.ts`]: handler,
+          });
+        }
+      }
+    }
+
+    // 3. Register sections from manifest (future — when apps export sections)
+    if (app.manifest.sections) {
+      registerSections(
+        app.manifest.sections as Record<string, () => Promise<any>>,
+      );
+    }
+
+    // 4. Always register app state (so getAppState() works for all apps)
+    registerAppState(app.name, app.state);
+
+    // 5. Register middleware (optional — not all apps have middleware)
+    if (app.middleware) {
+      registerAppMiddleware(app.name, app.middleware);
+    }
+  }
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "include": ["src/**/*"]
+}