@decocms/start 0.37.3 → 0.39.0

package/src/admin/index.ts

@@ -1,9 +1,11 @@
 export { corsHeaders, isAdminOrLocalhost, registerAdminOrigin, registerAdminOrigins } from "./cors";
 export { handleDecofileRead, handleDecofileReload } from "./decofile";
 export {
+  clearInvokeHandlers,
   handleInvoke,
   type InvokeAction,
   type InvokeLoader,
+  registerInvokeHandlers,
   setInvokeActions,
   setInvokeLoaders,
 } from "./invoke";

package/src/admin/invoke.ts

@@ -7,11 +7,21 @@
  * - FormData parsing for file uploads and form submissions
  * - `?select=field1,field2` to pick fields from the result
  * - Resolves __resolveType in batch payloads
+ *
+ * Handlers can write to `RequestContext.responseHeaders` to forward
+ * headers (e.g., Set-Cookie from VTEX checkout). The invoke endpoint
+ * copies those headers into the final HTTP Response.
  */
 
+import { RequestContext } from "../sdk/requestContext";
+
 export type InvokeLoader = (props: any, request: Request) => Promise<any>;
 export type InvokeAction = (props: any, request: Request) => Promise<any>;
 
+// Additive handler registry — registerInvokeHandlers() adds to this map.
+const handlerRegistry = new Map<string, InvokeLoader | InvokeAction>();
+
+// Legacy getter-based registries (backward compat for setInvokeLoaders/Actions).
 let getRegisteredLoaders: () => Record<string, InvokeLoader> = () => ({});
 let getRegisteredActions: () => Record<string, InvokeAction> = () => ({});
 
@@ -23,6 +33,29 @@ export function setInvokeActions(getter: () => Record<string, InvokeAction>) {
   getRegisteredActions = getter;
 }
 
+/**
+ * Additive handler registration — adds handlers without replacing existing ones.
+ * First registration wins: if a key already exists, it is NOT overwritten.
+ * Use this for automatic manifest-based registration from setupApps().
+ */
+export function registerInvokeHandlers(
+  handlers: Record<string, InvokeLoader | InvokeAction>,
+): void {
+  for (const [key, handler] of Object.entries(handlers)) {
+    if (!handlerRegistry.has(key)) {
+      handlerRegistry.set(key, handler);
+    }
+  }
+}
+
+/**
+ * Clear all registered invoke handlers.
+ * Called by setupApps() before re-registering on hot-reload.
+ */
+export function clearInvokeHandlers(): void {
+  handlerRegistry.clear();
+}
+
 const JSON_HEADERS = { "Content-Type": "application/json" } as const;
 
 const isDev =
@@ -100,6 +133,11 @@ async function parseBody(request: Request): Promise<any> {
 function findHandler(
   key: string,
 ): { handler: InvokeLoader | InvokeAction; type: "loader" | "action" } | null {
+  // 1. Check additive registry first (from registerInvokeHandlers / setupApps)
+  const registered = handlerRegistry.get(key);
+  if (registered) return { handler: registered, type: "action" };
+
+  // 2. Fall back to legacy getter-based registries
   const loaders = getRegisteredLoaders();
   if (loaders[key]) return { handler: loaders[key], type: "loader" };
 
@@ -126,15 +164,25 @@ export async function handleInvoke(request: Request): Promise<Response> {
 
     try {
       const result = await found.handler(body, request);
-      // Response passthrough: if the loader/action returns a Response object,
-      // forward it as-is (preserving headers like Set-Cookie). This matches
-      // deco-cx/deco's invokeToHttpResponse behavior where auth loaders return
-      // Response objects with Set-Cookie headers for HttpOnly cookies.
+      // Response passthrough: if the handler returns a Response object,
+      // forward it as-is (preserving headers like Set-Cookie).
       if (result instanceof Response) {
         return result;
       }
       const filtered = selectFields(result, select);
-      return new Response(JSON.stringify(filtered), { status: 200, headers: JSON_HEADERS });
+      const response = new Response(JSON.stringify(filtered), { status: 200, headers: JSON_HEADERS });
+
+      // Copy any headers that handlers wrote to RequestContext.responseHeaders
+      // (e.g., Set-Cookie from proxySetCookie). This mirrors deco-cx/deco's
+      // ctx.response.headers → HTTP Response forwarding.
+      const ctx = RequestContext.current;
+      if (ctx) {
+        for (const [key, value] of ctx.responseHeaders.entries()) {
+          response.headers.append(key, value);
+        }
+      }
+
+      return response;
     } catch (error) {
       return errorResponse((error as Error).message, 500, error);
     }

package/src/admin/setup.ts

@@ -8,7 +8,13 @@
  * import from "@decocms/start/admin" instead.
  */
 
-export { type InvokeAction, type InvokeLoader, setInvokeActions, setInvokeLoaders } from "./invoke";
+export {
+  type InvokeAction,
+  type InvokeLoader,
+  registerInvokeHandlers,
+  setInvokeActions,
+  setInvokeLoaders,
+} from "./invoke";
 export { setMetaData } from "./meta";
 export {
   type LoaderConfig,

package/src/apps/autoconfig.ts

@@ -1,9 +1,9 @@
 /**
- * Auto-configures known apps from CMS blocks.
+ * Auto-configures known apps from CMS blocks using AppModContract.
  *
- * Scans the decofile for known app block keys (e.g. "deco-resend") and:
- * 1. Configures the app client with CMS-provided credentials
- * 2. Registers invoke handlers so `invoke.app.actions.*` works via the proxy
+ * Scans the decofile for known app block keys (e.g. "deco-vtex", "deco-resend")
+ * and calls each app's `configure()` function from its mod.ts.
+ * Then delegates to `setupApps()` for invoke handler registration, middleware, etc.
  *
  * Usage in setup.ts:
  *   import { autoconfigApps } from "@decocms/start/apps/autoconfig";
@@ -11,62 +11,60 @@
  *   await autoconfigApps(generatedBlocks);
  */
 
-import { setInvokeActions, type InvokeAction } from "../admin/invoke";
 import { onChange } from "../cms/loader";
 import { resolveSecret } from "../sdk/crypto";
+import {
+	setupApps,
+	type AppDefinition,
+	type AppDefinitionWithHandlers,
+} from "../sdk/setupApps";
 
 // ---------------------------------------------------------------------------
-// Known app block keys → dynamic import + configure
+// Known app block keys → dynamic import of their mod.ts
 // ---------------------------------------------------------------------------
 
-interface AppAutoconfigurator {
-	/** Try to import, configure, and return invoke actions for this app */
-	(blockData: unknown): Promise<Record<string, InvokeAction>>;
-}
+const APP_MODS: Record<string, () => Promise<any>> = {
+	"deco-vtex": () => import("@decocms/apps/vtex/mod" as string),
+	"deco-shopify": () => import("@decocms/apps/shopify/mod" as string),
+	"deco-resend": () => import("@decocms/apps/resend/mod" as string),
+};
 
-const KNOWN_APPS: Record<string, AppAutoconfigurator> = {
-	"deco-resend": async (block: any): Promise<Record<string, InvokeAction>> => {
-		try {
-			const [resendClient, resendActions] = await Promise.all([
-				import("@decocms/apps/resend/client" as string),
-				import("@decocms/apps/resend/actions/send" as string),
-			]);
-			const { configureResend } = resendClient as { configureResend: (cfg: any) => void };
-			const { sendEmail } = resendActions as { sendEmail: (props: any) => Promise<any> };
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
 
-			const apiKey = await resolveSecret(block.apiKey, "RESEND_API_KEY");
-			if (!apiKey) {
-				console.warn(
-					"[autoconfig] deco-resend: no API key found." +
-					" Set DECO_CRYPTO_KEY to decrypt CMS secrets, or set RESEND_API_KEY as fallback.",
-				);
-				return {} as Record<string, InvokeAction>;
-			}
+async function configureAllApps(
+	blocks: Record<string, unknown>,
+): Promise<AppDefinitionWithHandlers[]> {
+	const apps: AppDefinitionWithHandlers[] = [];
 
-			configureResend({
-				apiKey,
-				emailFrom: block.emailFrom
-					? `${block.emailFrom.name || "Contact"} ${block.emailFrom.domain || "<onboarding@resend.dev>"}`
-					: undefined,
-				emailTo: block.emailTo,
-				subject: block.subject,
-			});
+	for (const [blockKey, importMod] of Object.entries(APP_MODS)) {
+		const block = blocks[blockKey];
+		if (!block) continue;
+
+		try {
+			const mod = await importMod();
+			if (typeof mod.configure !== "function") continue;
 
-			const handler: InvokeAction = async (props: any) => sendEmail(props);
-			return {
-				"resend/actions/emails/send": handler,
-				"resend/actions/emails/send.ts": handler,
+			const appDef: AppDefinition | null = await mod.configure(
+				block,
+				resolveSecret,
+			);
+			if (!appDef) continue;
+
+			// Attach explicit handlers from mod.ts (e.g. resend's pre-wrapped handlers)
+			const withHandlers: AppDefinitionWithHandlers = {
+				...appDef,
+				handlers: mod.handlers,
 			};
+			apps.push(withHandlers);
 		} catch {
-			// @decocms/apps not installed or doesn't have resend — skip
-			return {};
+			// App not installed or configure failed — skip silently
 		}
-	},
-};
+	}
 
-// ---------------------------------------------------------------------------
-// Main
-// ---------------------------------------------------------------------------
+	return apps;
+}
 
 /**
  * Auto-configure apps from CMS blocks.
@@ -75,37 +73,17 @@ const KNOWN_APPS: Record<string, AppAutoconfigurator> = {
 export async function autoconfigApps(blocks: Record<string, unknown>) {
 	if (typeof document !== "undefined") return; // server-only
 
-	const actions: Record<string, InvokeAction> = {};
-
-	for (const [blockKey, configurator] of Object.entries(KNOWN_APPS)) {
-		const block = blocks[blockKey];
-		if (!block) continue;
-
-		try {
-			const appActions = await configurator(block);
-			Object.assign(actions, appActions);
-		} catch (e) {
-			console.warn(`[autoconfig] ${blockKey}:`, e);
-		}
-	}
-
-	if (Object.keys(actions).length > 0) {
-		setInvokeActions(() => ({ ...actions }));
+	const apps = await configureAllApps(blocks);
+	if (apps.length > 0) {
+		await setupApps(apps);
 	}
 
 	// Re-configure on admin hot-reload
 	onChange(async (newBlocks) => {
 		if (typeof document !== "undefined") return;
-		const updatedActions: Record<string, InvokeAction> = {};
-		for (const [blockKey, configurator] of Object.entries(KNOWN_APPS)) {
-			const block = newBlocks[blockKey];
-			if (!block) continue;
-			try {
-				Object.assign(updatedActions, await configurator(block));
-			} catch {}
-		}
-		if (Object.keys(updatedActions).length > 0) {
-			setInvokeActions(() => ({ ...updatedActions }));
+		const updatedApps = await configureAllApps(newBlocks);
+		if (updatedApps.length > 0) {
+			await setupApps(updatedApps);
 		}
 	});
 }

package/src/sdk/invoke.ts

@@ -1,21 +1,22 @@
 /**
- * Typed invoke proxy for client-side RPC to deco loaders/actions.
+ * Typed invoke proxies for client-side RPC to deco loaders/actions.
  *
- * Creates a Proxy object that maps loader keys to `POST /deco/invoke/:key` calls,
- * providing a type-safe, ergonomic API for client-side data fetching.
+ * Two flavors:
+ *
+ * 1. `createInvokeProxy<T>()` — flat keys (e.g. `invoke["vtex/loaders/productList.ts"](props)`)
+ * 2. `createAppInvoke<T>()` — nested keys (e.g. `invoke.vtex.actions.checkout.addItemsToCart(props)`)
+ *
+ * Both POST to `/deco/invoke/{key}` under the hood.
  *
  * @example
  * ```ts
- * // Define your loader registry type
- * type Loaders = {
- *   "vtex/loaders/intelligentSearch/productList.ts": (props: { query: string }) => Promise<Product[]>;
- *   "vtex/loaders/intelligentSearch/productDetailsPage.ts": (props: { slug: string }) => Promise<ProductDetailsPage>;
- * };
+ * // Flat proxy (legacy):
+ * const invoke = createInvokeProxy<Loaders>();
+ * await invoke["vtex/loaders/productList.ts"]({ query: "shoes" });
  *
- * const invoke = createInvokeProxy<Loaders>("/deco/invoke");
- *
- * // Type-safe calls:
- * const products = await invoke["vtex/loaders/intelligentSearch/productList.ts"]({ query: "shoes" });
+ * // Nested proxy (recommended):
+ * const invoke = createAppInvoke();
+ * await invoke.vtex.actions.checkout.addItemsToCart({ orderFormId, orderItems });
  * ```
  */
 
@@ -131,3 +132,113 @@ export function invokeQueryOptions<TResult = unknown>(
     gcTime: options?.gcTime,
   };
 }
+
+// ---------------------------------------------------------------------------
+// Nested invoke proxy — createAppInvoke
+// ---------------------------------------------------------------------------
+
+/**
+ * Converts flat slash-separated keys into a nested object type.
+ *
+ * @example
+ * ```ts
+ * type Map = {
+ *   "vtex/actions/checkout/addItemsToCart": (props: CartInput) => Promise<OrderForm>;
+ *   "vtex/loaders/catalog/getProduct": (props: { slug: string }) => Promise<Product>;
+ * };
+ * type Nested = NestedFromFlat<Map>;
+ * // { vtex: { actions: { checkout: { addItemsToCart: (props: CartInput) => Promise<OrderForm> } } } }
+ * ```
+ */
+type SplitFirst<S extends string> = S extends `${infer Head}/${infer Tail}`
+  ? [Head, Tail]
+  : [S, never];
+
+type BuildNested<Key extends string, Value> = SplitFirst<Key> extends [
+  infer H extends string,
+  infer T,
+]
+  ? T extends string
+    ? { [K in H]: BuildNested<T, Value> }
+    : { [K in H]: Value }
+  : never;
+
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
+  k: infer I,
+) => void
+  ? I
+  : never;
+
+type DeepMerge<T> = T extends object
+  ? { [K in keyof T]: DeepMerge<T[K]> }
+  : T;
+
+export type NestedFromFlat<T extends Record<string, any>> = DeepMerge<
+  UnionToIntersection<
+    { [K in keyof T & string]: BuildNested<K, T[K]> }[keyof T & string]
+  >
+>;
+
+/**
+ * Creates a typed nested invoke proxy.
+ *
+ * Each property access accumulates path segments. When called as a function,
+ * the segments are joined with "/" and POSTed to `/deco/invoke/{key}`.
+ * If the primary key returns 404, a `.ts` suffix variant is tried.
+ *
+ * @example
+ * ```ts
+ * import { createAppInvoke } from "@decocms/start/sdk/invoke";
+ *
+ * // Untyped (any):
+ * const invoke = createAppInvoke();
+ * await invoke.vtex.actions.checkout.addItemsToCart({ orderFormId, orderItems });
+ *
+ * // Typed (with handler map):
+ * type Handlers = {
+ *   "vtex/actions/checkout/addItemsToCart": (props: CartInput) => Promise<OrderForm>;
+ * };
+ * const invoke = createAppInvoke<Handlers>();
+ * await invoke.vtex.actions.checkout.addItemsToCart({ orderFormId, orderItems });
+ * ```
+ */
+export function createAppInvoke(basePath?: string): any;
+export function createAppInvoke<T extends Record<string, any>>(basePath?: string): NestedFromFlat<T>;
+export function createAppInvoke(
+  basePath = "/deco/invoke",
+): any {
+  function buildProxy(path: string[]): any {
+    return new Proxy(
+      Object.assign(async (props: any) => {
+        const key = path.join("/");
+        for (const k of [key, `${key}.ts`]) {
+          const response = await fetch(`${basePath}/${k}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(props ?? {}),
+          });
+          if (response.status === 404) { await response.body?.cancel(); continue; }
+          if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: response.statusText }));
+            throw new Error(
+              `invoke(${k}) failed (${response.status}): ${(error as any).error || response.statusText}`,
+            );
+          }
+          return response.json();
+        }
+        throw new Error(`invoke(${key}) failed: handler not found`);
+      }, {}),
+      {
+        get(_target: any, prop: string | symbol) {
+          if (typeof prop === "symbol") return undefined;
+          if (prop === "then" || prop === "catch" || prop === "finally") {
+            return undefined;
+          }
+          return buildProxy([...path, prop]);
+        },
+      },
+    );
+  }
+
+  return buildProxy([]);
+}

package/src/sdk/requestContext.ts

@@ -44,6 +44,17 @@ export interface RequestContextData {
   _isBot?: boolean;
   /** Arbitrary bag for middleware to attach custom data. */
   bag: Map<string, unknown>;
+  /**
+   * Outgoing response headers that handlers can write to.
+   * Invoke handlers (actions/loaders) use this to forward Set-Cookie
+   * and other headers from upstream APIs (e.g., VTEX checkout).
+   * The invoke HTTP handler copies these into the final Response.
+   *
+   * This mirrors deco-cx/deco's `ctx.response.headers` pattern where
+   * `proxySetCookie(apiResponse.headers, ctx.response.headers)` forwards
+   * cookies transparently.
+   */
+  responseHeaders: Headers;
 }
 
 // -------------------------------------------------------------------------
@@ -87,6 +98,7 @@ export const RequestContext = {
       signal: controller.signal,
       startedAt: Date.now(),
       bag: new Map(),
+      responseHeaders: new Headers(),
     };
 
     return storage.run(ctx, fn);
@@ -169,6 +181,17 @@ export const RequestContext = {
     });
   },
 
+  /**
+   * Outgoing response headers. Handlers write here; the invoke endpoint
+   * copies them into the HTTP Response (mirroring ctx.response.headers
+   * from deco-cx/deco).
+   */
+  get responseHeaders(): Headers {
+    const ctx = storage.getStore();
+    if (!ctx) throw new Error("RequestContext.responseHeaders accessed outside a request scope");
+    return ctx.responseHeaders;
+  },
+
   /**
    * Get/set arbitrary values in the request bag.
    * Useful for middleware to pass data to loaders.
@@ -182,4 +205,23 @@ export const RequestContext = {
     const ctx = storage.getStore();
     ctx?.bag.set(key, value);
   },
+
+  /**
+   * Get an app's state from the request bag.
+   * Apps register their state via `setupApps()` which injects it
+   * into the bag as `app:{name}:state` before each request.
+   *
+   * @example
+   * ```ts
+   * import { RequestContext } from "@decocms/start/sdk/requestContext";
+   * import type { VtexState } from "@decocms/apps/vtex/mod";
+   *
+   * const vtex = RequestContext.getAppState<VtexState>("vtex");
+   * if (vtex) console.log(vtex.config.account);
+   * ```
+   */
+  getAppState<T>(appName: string): T | undefined {
+    const ctx = storage.getStore();
+    return ctx?.bag.get(`app:${appName}:state`) as T | undefined;
+  },
 };