@decocms/apps 0.26.0 → 0.28.0

package/commerce/app-types.ts

@@ -0,0 +1,62 @@
+/**
+ * Core types for the Deco app system on TanStack Start.
+ *
+ * Each app (vtex, shopify, resend, etc.) exports a `configure` function
+ * from its `mod.ts` that returns an `AppDefinition`.
+ *
+ * The framework's `autoconfigApps()` calls these generically.
+ */
+
+import type { ComponentType } from "react";
+
+export type AppHandler = (props: any, request: Request) => Promise<any>;
+
+export interface SectionModule {
+	default: ComponentType<Record<string, unknown>>;
+	loader?: (...args: unknown[]) => Promise<unknown> | unknown;
+	LoadingFallback?: ComponentType;
+	ErrorFallback?: ComponentType<{ error: Error }>;
+}
+
+export interface AppManifest {
+	name: string;
+	/** Module namespace imports keyed by manifest path (e.g. "vtex/loaders/catalog"). */
+	loaders: Record<string, Record<string, unknown>>;
+	/** Module namespace imports keyed by manifest path (e.g. "vtex/actions/checkout"). */
+	actions: Record<string, Record<string, unknown>>;
+	/** Lazy-loaded section components keyed by manifest path (e.g. "vtex/sections/Analytics/Vtex"). */
+	sections?: Record<string, () => Promise<SectionModule>>;
+}
+
+export type AppMiddleware = (request: Request, next: () => Promise<Response>) => Promise<Response>;
+
+export interface AppDefinition<TState = unknown> {
+	name: string;
+	manifest: AppManifest;
+	state: TState;
+	middleware?: AppMiddleware;
+	dependencies?: AppDefinition[];
+	resolvables?: Record<string, { __resolveType: string; [key: string]: unknown }>;
+}
+
+export type ResolveSecretFn = (value: unknown, envKey: string) => Promise<string | null>;
+
+export interface AppPreview {
+	Component: ComponentType<Record<string, unknown>>;
+	props: Record<string, unknown>;
+}
+
+/**
+ * Standard contract for Deco apps with auto-configuration.
+ *
+ * Each app exports `configure` from its `mod.ts`.
+ * Apps that need invoke handlers (e.g. resend) also export a `handlers` map.
+ * The framework discovers and calls these generically.
+ */
+export interface AppModContract<TState = unknown> {
+	configure: (
+		blockData: any,
+		resolveSecret: ResolveSecretFn,
+	) => Promise<AppDefinition<TState> | null>;
+	handlers?: Record<string, AppHandler>;
+}

package/commerce/manifest-utils.ts

@@ -0,0 +1,38 @@
+/**
+ * Utilities for extracting individual handlers from app manifests.
+ *
+ * Used by the framework to flatten module namespace imports into
+ * individual handler functions for setInvokeLoaders() / setInvokeActions().
+ */
+
+import type { AppManifest } from "./app-types";
+
+/**
+ * Extract individual handler functions from a manifest's module namespaces.
+ *
+ * Given a manifest with:
+ *   loaders: { "vtex/loaders/catalog": { searchProducts, getProductByIdOrSku } }
+ *
+ * Returns:
+ *   { "vtex/loaders/catalog/searchProducts": searchProducts, ... }
+ */
+type AnyFn = (...args: never[]) => unknown;
+
+export function extractHandlers(manifest: AppManifest): Record<string, AnyFn> {
+	const result: Record<string, AnyFn> = {};
+
+	for (const category of ["loaders", "actions"] as const) {
+		const modules = manifest[category];
+		for (const [moduleKey, moduleNamespace] of Object.entries(modules)) {
+			for (const [exportName, handler] of Object.entries(
+				moduleNamespace as Record<string, unknown>,
+			)) {
+				if (typeof handler === "function") {
+					result[`${moduleKey}/${exportName}`] = handler as AnyFn;
+				}
+			}
+		}
+	}
+
+	return result;
+}

package/commerce/resolve.ts

@@ -0,0 +1,114 @@
+/**
+ * App composition utilities.
+ *
+ * Merges manifests and chains middleware from multiple AppDefinitions
+ * into a single resolved structure.
+ *
+ * @example
+ * ```ts
+ * import { resolveApps } from "@decocms/apps/commerce/resolve";
+ * import * as vtexApp from "@decocms/apps/vtex/mod";
+ * import * as resendApp from "@decocms/apps/resend/mod";
+ *
+ * const apps = await Promise.all([
+ *   vtexApp.configure(blocks.vtex, resolveSecret),
+ *   resendApp.configure(blocks.resend, resolveSecret),
+ * ]);
+ *
+ * const resolved = resolveApps(apps.filter(Boolean));
+ * // resolved.manifest — merged manifest from all apps
+ * // resolved.middleware — chained middleware (or undefined)
+ * ```
+ */
+
+import type { AppDefinition, AppManifest, AppMiddleware } from "./app-types";
+
+export interface ResolvedApps {
+	manifest: AppManifest;
+	middleware: AppMiddleware | undefined;
+	resolvables: Record<string, { __resolveType: string; [key: string]: unknown }>;
+}
+
+/**
+ * Resolve an array of app definitions into a single merged structure.
+ *
+ * - Manifests are merged (loaders/actions from all apps).
+ * - Middleware is chained in array order (first app runs outermost).
+ */
+export function resolveApps(apps: AppDefinition[]): ResolvedApps {
+	const mergedManifest: AppManifest = {
+		name: "resolved",
+		loaders: {},
+		actions: {},
+		sections: {},
+	};
+
+	const middlewares: AppMiddleware[] = [];
+	const resolvables: Record<string, { __resolveType: string; [key: string]: unknown }> = {};
+
+	for (const app of flattenDependencies(apps)) {
+		Object.assign(mergedManifest.loaders, app.manifest.loaders);
+		Object.assign(mergedManifest.actions, app.manifest.actions);
+
+		if (app.manifest.sections) {
+			Object.assign(mergedManifest.sections!, app.manifest.sections);
+		}
+
+		if (app.resolvables) {
+			Object.assign(resolvables, app.resolvables);
+		}
+
+		if (app.middleware) {
+			middlewares.push(app.middleware);
+		}
+	}
+
+	return {
+		manifest: mergedManifest,
+		middleware: middlewares.length > 0 ? chainMiddleware(middlewares) : undefined,
+		resolvables,
+	};
+}
+
+/**
+ * Flatten the dependency graph (depth-first, dependencies before dependents).
+ * Deduplicates by app name.
+ */
+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;
+}
+
+/**
+ * Chain multiple middleware functions into a single one.
+ * First middleware in the array runs outermost (wraps the rest).
+ */
+function chainMiddleware(middlewares: AppMiddleware[]): AppMiddleware {
+	return async (request, next) => {
+		const run = async (i: number): Promise<Response> => {
+			if (i < 0) return next();
+			return middlewares[i](request, () => run(i - 1));
+		};
+
+		return run(middlewares.length - 1);
+	};
+}

package/commerce/sdk/formatPrice.ts

@@ -20,7 +20,4 @@ export const formatPrice = (
 	price: number | undefined | null,
 	currency = "BRL",
 	locale = "pt-BR",
-) =>
-	price != null && Number.isFinite(price)
-		? formatter(currency, locale).format(price)
-		: null;
+) => (price != null && Number.isFinite(price) ? formatter(currency, locale).format(price) : null);

package/package.json

@@ -1,16 +1,20 @@
 {
   "name": "@decocms/apps",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "type": "module",
   "description": "Deco commerce apps for TanStack Start - Shopify, VTEX, commerce types, analytics utils",
   "exports": {
     "./commerce/types": "./commerce/types/commerce.ts",
+    "./commerce/app-types": "./commerce/app-types.ts",
+    "./commerce/resolve": "./commerce/resolve.ts",
+    "./commerce/manifest-utils": "./commerce/manifest-utils.ts",
     "./commerce/components/JsonLd": "./commerce/components/JsonLd.tsx",
     "./commerce/components/Image": "./commerce/components/Image.tsx",
     "./commerce/components/Picture": "./commerce/components/Picture.tsx",
     "./commerce/utils/*": "./commerce/utils/*.ts",
     "./commerce/sdk/*": "./commerce/sdk/*.ts",
     "./shopify": "./shopify/index.ts",
+    "./shopify/mod": "./shopify/mod.ts",
     "./shopify/client": "./shopify/client.ts",
     "./shopify/loaders/*": "./shopify/loaders/*.ts",
     "./shopify/actions/*": "./shopify/actions/*.ts",
@@ -18,6 +22,7 @@
     "./shopify/actions/user/*": "./shopify/actions/user/*.ts",
     "./shopify/utils/*": "./shopify/utils/*.ts",
     "./vtex": "./vtex/index.ts",
+    "./vtex/mod": "./vtex/mod.ts",
     "./vtex/client": "./vtex/client.ts",
     "./vtex/types": "./vtex/types.ts",
     "./vtex/actions": "./vtex/actions/index.ts",
@@ -37,13 +42,14 @@
     "./vtex/hooks/*": "./vtex/hooks/*.ts",
     "./vtex/inline-loaders/workflowProducts": "./vtex/inline-loaders/workflowProducts.ts",
     "./vtex/middleware": "./vtex/middleware.ts",
-    "./vtex/invoke": "./vtex/invoke.ts",
     "./resend": "./resend/index.ts",
+    "./resend/mod": "./resend/mod.ts",
     "./resend/client": "./resend/client.ts",
     "./resend/types": "./resend/types.ts",
     "./resend/actions/send": "./resend/actions/send.ts"
   },
   "scripts": {
+    "generate:manifests": "tsx scripts/generate-manifests.ts",
     "typecheck": "tsc --noEmit",
     "lint:unused": "knip",
     "lint:unused:fix": "knip --fix",
@@ -73,7 +79,8 @@
     "shopify/",
     "vtex/",
     "resend/",
-    "!**/__tests__/"
+    "!**/__tests__/",
+    "!scripts/"
   ],
   "engines": {
     "node": ">=18"
@@ -90,7 +97,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.7",
-    "@decocms/start": "^0.29.3",
+    "@decocms/start": "^0.38.0",
     "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^10.0.1",
     "@tanstack/react-query": "^5.90.21",
@@ -99,6 +106,7 @@
     "knip": "^5.86.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0"
   }

package/resend/manifest.gen.ts

@@ -0,0 +1,15 @@
+// AUTO-GENERATED by scripts/generate-manifests.ts — DO NOT EDIT
+// This file is checked into source control and updated via: npm run generate:manifests
+import * as actions_send from "./actions/send";
+
+const manifest = {
+	name: "resend",
+	loaders: {},
+	actions: {
+		"resend/actions/send": actions_send,
+	},
+	sections: {},
+} as const;
+
+export type Manifest = typeof manifest;
+export default manifest;

package/resend/mod.ts

@@ -0,0 +1,67 @@
+/**
+ * Resend app module — standard autoconfig contract.
+ *
+ * Exports `configure` and `handlers` following the AppModContract pattern.
+ * The framework's `autoconfigApps()` calls these generically — no hardcoded
+ * app knowledge needed in the framework.
+ */
+
+import type { AppDefinition, AppHandler, ResolveSecretFn } from "../commerce/app-types";
+import { sendEmail } from "./actions/send";
+import { configureResend } from "./client";
+import manifest from "./manifest.gen";
+import type { ResendConfig } from "./types";
+
+// -------------------------------------------------------------------------
+// State
+// -------------------------------------------------------------------------
+
+export interface ResendState {
+	config: ResendConfig;
+}
+
+// -------------------------------------------------------------------------
+// Configure
+// -------------------------------------------------------------------------
+
+/**
+ * Configure Resend from CMS block data.
+ * Returns an AppDefinition or null if missing credentials.
+ */
+export async function configure(
+	block: any,
+	resolveSecret: ResolveSecretFn,
+): Promise<AppDefinition<ResendState> | null> {
+	const apiKey = await resolveSecret(block.apiKey, "RESEND_API_KEY");
+	if (!apiKey) return null;
+
+	const config: ResendConfig = {
+		apiKey,
+		emailFrom: block.emailFrom
+			? `${block.emailFrom.name || "Contact"} <${block.emailFrom.domain || "onboarding@resend.dev"}>`
+			: undefined,
+		emailTo: block.emailTo,
+		subject: block.subject,
+	};
+
+	// Bridge: maintain global singleton for backward compat
+	configureResend(config);
+
+	return {
+		name: "resend",
+		manifest,
+		state: { config },
+	};
+}
+
+/**
+ * Invoke handlers registered under /deco/invoke/{key}.
+ * Both with and without .ts suffix for compatibility.
+ */
+export const handlers: Record<string, AppHandler> = {
+	"resend/actions/emails/send": (props) => sendEmail(props),
+	"resend/actions/emails/send.ts": (props) => sendEmail(props),
+};
+
+/** Placeholder preview for CMS editor — evolves when admin supports it. */
+export const preview = undefined;

package/shopify/index.ts

@@ -1,3 +1,6 @@
+// App contract
+export { configure, type ShopifyState } from "./mod";
+
 // Client & Config
 
 export { default as addItems } from "./actions/cart/addItems";

package/shopify/manifest.gen.ts

@@ -0,0 +1,39 @@
+// AUTO-GENERATED by scripts/generate-manifests.ts — DO NOT EDIT
+// This file is checked into source control and updated via: npm run generate:manifests
+
+import * as actions_cart_addItems from "./actions/cart/addItems";
+import * as actions_cart_updateCoupons from "./actions/cart/updateCoupons";
+import * as actions_cart_updateItems from "./actions/cart/updateItems";
+import * as actions_user_signIn from "./actions/user/signIn";
+import * as actions_user_signUp from "./actions/user/signUp";
+import * as loaders_cart from "./loaders/cart";
+import * as loaders_ProductDetailsPage from "./loaders/ProductDetailsPage";
+import * as loaders_ProductList from "./loaders/ProductList";
+import * as loaders_ProductListingPage from "./loaders/ProductListingPage";
+import * as loaders_RelatedProducts from "./loaders/RelatedProducts";
+import * as loaders_shop from "./loaders/shop";
+import * as loaders_user from "./loaders/user";
+
+const manifest = {
+	name: "shopify",
+	loaders: {
+		"shopify/loaders/ProductDetailsPage": loaders_ProductDetailsPage,
+		"shopify/loaders/ProductList": loaders_ProductList,
+		"shopify/loaders/ProductListingPage": loaders_ProductListingPage,
+		"shopify/loaders/RelatedProducts": loaders_RelatedProducts,
+		"shopify/loaders/cart": loaders_cart,
+		"shopify/loaders/shop": loaders_shop,
+		"shopify/loaders/user": loaders_user,
+	},
+	actions: {
+		"shopify/actions/cart/addItems": actions_cart_addItems,
+		"shopify/actions/cart/updateCoupons": actions_cart_updateCoupons,
+		"shopify/actions/cart/updateItems": actions_cart_updateItems,
+		"shopify/actions/user/signIn": actions_user_signIn,
+		"shopify/actions/user/signUp": actions_user_signUp,
+	},
+	sections: {},
+} as const;
+
+export type Manifest = typeof manifest;
+export default manifest;

package/shopify/mod.ts

@@ -0,0 +1,67 @@
+/**
+ * Shopify app module — standard autoconfig contract.
+ *
+ * Exports `configure` following the AppModContract pattern.
+ * The framework's `autoconfigApps()` calls these generically.
+ *
+ * @example
+ * ```ts
+ * import * as shopifyApp from "@decocms/apps/shopify/mod";
+ *
+ * const app = await shopifyApp.configure(blocks["deco-shopify"], resolveSecret);
+ * if (app) {
+ *   // app.manifest, app.state are available
+ * }
+ * ```
+ */
+
+import type { AppDefinition, ResolveSecretFn } from "../commerce/app-types";
+import { configureShopify, type ShopifyConfig } from "./client";
+import manifest from "./manifest.gen";
+
+// -------------------------------------------------------------------------
+// State
+// -------------------------------------------------------------------------
+
+export interface ShopifyState {
+	config: ShopifyConfig;
+}
+
+// -------------------------------------------------------------------------
+// Configure
+// -------------------------------------------------------------------------
+
+/**
+ * Configure the Shopify app from CMS block data.
+ * Returns an AppDefinition or null if required fields are missing.
+ */
+export async function configure(
+	block: any,
+	resolveSecret: ResolveSecretFn,
+): Promise<AppDefinition<ShopifyState> | null> {
+	if (!block?.storeName) return null;
+
+	const storefrontAccessToken =
+		(await resolveSecret(block.storefrontAccessToken, "SHOPIFY_STOREFRONT_TOKEN")) ??
+		(typeof block.storefrontAccessToken === "string" ? block.storefrontAccessToken : null);
+
+	if (!storefrontAccessToken) return null;
+
+	const config: ShopifyConfig = {
+		storeName: block.storeName,
+		storefrontAccessToken,
+		publicUrl: block.publicUrl,
+	};
+
+	// Bridge: maintain global singleton for backward compat
+	configureShopify(config);
+
+	return {
+		name: "shopify",
+		manifest,
+		state: { config },
+	};
+}
+
+/** Placeholder preview for CMS editor — evolves when admin supports it. */
+export const preview = undefined;