@decocms/apps 0.27.0 → 0.28.1

package/vtex/actions/masterData.ts

@@ -16,25 +16,37 @@ export interface CreateDocumentResult {
 	DocumentId: string;
 }
 
-export async function createDocument(
-	entity: string,
-	data: Record<string, any>,
-): Promise<CreateDocumentResult> {
+export interface CreateDocumentProps {
+	entity: string;
+	data: Record<string, any>;
+}
+
+export async function createDocument(props: CreateDocumentProps): Promise<CreateDocumentResult> {
+	const { entity, data } = props;
 	return vtexFetch<CreateDocumentResult>(`/api/dataentities/${entity}/documents`, {
 		method: "POST",
 		body: JSON.stringify(removeEmptyFields(data)),
 	});
 }
 
-export async function getDocument<T = unknown>(entity: string, documentId: string): Promise<T> {
+export interface GetDocumentProps {
+	entity: string;
+	documentId: string;
+}
+
+export async function getDocument<T = unknown>(props: GetDocumentProps): Promise<T> {
+	const { entity, documentId } = props;
 	return vtexFetch<T>(`/api/dataentities/${entity}/documents/${documentId}`);
 }
 
-export async function patchDocument(
-	entity: string,
-	documentId: string,
-	data: Record<string, any>,
-): Promise<void> {
+export interface PatchDocumentProps {
+	entity: string;
+	documentId: string;
+	data: Record<string, any>;
+}
+
+export async function patchDocument(props: PatchDocumentProps): Promise<void> {
+	const { entity, documentId, data } = props;
 	await vtexFetch<any>(`/api/dataentities/${entity}/documents/${documentId}`, {
 		method: "PATCH",
 		body: JSON.stringify(removeEmptyFields(data)),
@@ -49,13 +61,18 @@ export interface MasterDataSearchResult {
 	[key: string]: any;
 }
 
+export interface SearchDocumentsProps {
+	entity: string;
+	filter: string;
+}
+
 /**
  * Simple search — kept for backward compat.
  */
 export async function searchDocuments<T = MasterDataSearchResult>(
-	entity: string,
-	filter: string,
+	props: SearchDocumentsProps,
 ): Promise<T[]> {
+	const { entity, filter } = props;
 	return vtexFetch<T[]>(`/api/dataentities/${entity}/search?_where=${encodeURIComponent(filter)}`);
 }
 
@@ -65,7 +82,7 @@ export async function searchDocuments<T = MasterDataSearchResult>(
  *
  * @see https://developers.vtex.com/docs/api-reference/masterdata-api#get-/api/dataentities/-acronym-/search
  */
-export interface SearchDocumentsOpts {
+export interface SearchDocumentsFullProps {
 	acronym: string;
 	fields?: string;
 	where?: string;
@@ -74,14 +91,12 @@ export interface SearchDocumentsOpts {
 	take?: number;
 	/** @default 0 */
 	skip?: number;
-	/** Auth cookie header for authenticated queries */
-	cookieHeader?: string;
 }
 
 export async function searchDocumentsFull<T = Record<string, unknown>>(
-	opts: SearchDocumentsOpts,
+	props: SearchDocumentsFullProps,
 ): Promise<T[]> {
-	const { acronym, fields, where, sort, skip = 0, take = 10, cookieHeader } = opts;
+	const { acronym, fields, where, sort, skip = 0, take = 10 } = props;
 	const from = Math.max(skip, 0);
 	const to = from + Math.min(100, take);
 
@@ -95,7 +110,6 @@ export async function searchDocumentsFull<T = Record<string, unknown>>(
 		"content-type": "application/json",
 		"REST-Range": `resources=${from}-${to}`,
 	};
-	if (cookieHeader) headers.cookie = cookieHeader;
 
 	return vtexFetchResponse(`/api/dataentities/${acronym}/search?${params}`, {
 		headers,

package/vtex/actions/session.ts

@@ -1,9 +1,8 @@
 /**
  * VTEX Sessions API actions.
- * All session-mutating actions return Set-Cookie headers for propagation.
+ * Cookie forwarding happens automatically via RequestContext.responseHeaders.
  */
 
-import type { VtexFetchResult } from "../client";
 import { getVtexConfig, vtexFetchWithCookies, vtexIOGraphQL } from "../client";
 import { buildAuthCookieHeader } from "../utils/vtexId";
 
@@ -16,16 +15,15 @@ export interface SessionData {
 	namespaces: Record<string, Record<string, { value: string }>>;
 }
 
-export async function createSession(
-	data: Record<string, any>,
-	cookieHeader?: string,
-): Promise<VtexFetchResult<SessionData>> {
-	const headers: Record<string, string> = {};
-	if (cookieHeader) headers.cookie = cookieHeader;
+export interface CreateSessionProps {
+	data: Record<string, any>;
+}
+
+export async function createSession(props: CreateSessionProps): Promise<SessionData> {
+	const { data } = props;
 	return vtexFetchWithCookies<SessionData>("/api/sessions", {
 		method: "POST",
 		body: JSON.stringify(data),
-		headers,
 	});
 }
 
@@ -38,21 +36,17 @@ export interface EditSessionResponse {
 	namespaces: Record<string, Record<string, { value: string }>>;
 }
 
+export interface EditSessionProps {
+	public: Record<string, { value: string }>;
+}
+
 /**
  * Edit the current VTEX session (public properties).
- * Returns data + Set-Cookie headers.
  */
-export async function editSession(
-	publicProperties: Record<string, { value: string }>,
-	cookieHeader?: string,
-): Promise<VtexFetchResult<EditSessionResponse>> {
-	const headers: Record<string, string> = {};
-	if (cookieHeader) headers.cookie = cookieHeader;
-
+export async function editSession(props: EditSessionProps): Promise<EditSessionResponse> {
 	return vtexFetchWithCookies<EditSessionResponse>("/api/sessions", {
 		method: "PATCH",
-		body: JSON.stringify({ public: { ...publicProperties } }),
-		headers,
+		body: JSON.stringify({ public: { ...props.public } }),
 	});
 }
 
@@ -68,14 +62,17 @@ const DELETE_SESSION_MUTATION = `mutation LogOutFromSession($sessionId: ID) {
   logOutFromSession(sessionId: $sessionId) @context(provider: "vtex.store-graphql@2.x")
 }`;
 
+export interface DeleteSessionProps {
+	sessionId: string;
+	authCookie: string;
+}
+
 /**
  * Log out / delete a VTEX session via the store-graphql mutation.
  * Requires a valid auth cookie.
  */
-export async function deleteSession(
-	sessionId: string,
-	authCookie: string,
-): Promise<DeleteSessionResponse> {
+export async function deleteSession(props: DeleteSessionProps): Promise<DeleteSessionResponse> {
+	const { sessionId, authCookie } = props;
 	if (!authCookie) throw new Error("Auth cookie is required to delete session");
 	const { account } = getVtexConfig();
 	return vtexIOGraphQL<DeleteSessionResponse>(

package/vtex/client.ts

@@ -3,9 +3,29 @@
  * Uses VTEX's public REST APIs (Intelligent Search + Catalog + Checkout).
  */
 
+import { RequestContext } from "@decocms/start/sdk/requestContext";
 import { type FetchCacheOptions, fetchWithCache } from "./utils/fetchCache";
 import { parseSegment, SEGMENT_COOKIE_NAME } from "./utils/segment";
 
+/**
+ * Get the response headers from RequestContext.
+ * Uses `responseHeaders` when available (@decocms/start PR#57),
+ * falls back to the bag with a lazily-created Headers instance.
+ * TODO: Remove fallback once @decocms/start PR#57 is published.
+ */
+function getResponseHeaders(): Headers | null {
+	const ctx = RequestContext.current;
+	if (!ctx) return null;
+	// biome-ignore lint/suspicious/noExplicitAny: forward-compat with upcoming responseHeaders property
+	if ((ctx as any).responseHeaders instanceof Headers) return (ctx as any).responseHeaders;
+	let headers = ctx.bag.get("responseHeaders") as Headers | undefined;
+	if (!headers) {
+		headers = new Headers();
+		ctx.bag.set("responseHeaders", headers);
+	}
+	return headers;
+}
+
 // ---------------------------------------------------------------------------
 // URL sanitization (ported from deco-cx/apps vtex/utils/fetchVTEX.ts)
 // ---------------------------------------------------------------------------
@@ -82,8 +102,6 @@ export interface VtexConfig {
 
 let _config: VtexConfig | null = null;
 let _fetch: typeof fetch = globalThis.fetch;
-let _getCookieHeader: (() => string | undefined) | null = null;
-let _forwardSetCookies: ((cookies: string[]) => void) | null = null;
 
 export function configureVtex(config: VtexConfig) {
 	_config = config;
@@ -105,37 +123,6 @@ export function setVtexFetch(fetchFn: typeof fetch) {
 	_fetch = fetchFn;
 }
 
-/**
- * Register a provider that returns the Cookie header from the current request.
- * Called automatically by vtexFetchWithCookies when no explicit cookieHeader
- * is present in the request init — so checkout/session/auth actions
- * transparently forward browser cookies to the VTEX API.
- *
- * @example
- * ```ts
- * import { getRequestHeader } from "@tanstack/react-start/server";
- * setRequestCookieProvider(() => getRequestHeader("cookie") ?? undefined);
- * ```
- */
-export function setRequestCookieProvider(fn: () => string | undefined) {
-	_getCookieHeader = fn;
-}
-
-/**
- * Register a callback that forwards VTEX Set-Cookie headers back to the browser.
- * Called automatically by vtexFetchWithCookies after every response that
- * carries Set-Cookie headers.
- *
- * @example
- * ```ts
- * import { setResponseHeader } from "@tanstack/react-start/server";
- * setResponseCookieForwarder((cookies) => setResponseHeader("set-cookie", cookies));
- * ```
- */
-export function setResponseCookieForwarder(fn: (cookies: string[]) => void) {
-	_forwardSetCookies = fn;
-}
-
 export function getVtexConfig(): VtexConfig {
 	if (!_config) throw new Error("VTEX not configured. Call configureVtex() first.");
 	return _config;
@@ -174,11 +161,12 @@ function authHeaders(): Record<string, string> {
 
 /**
  * Read regionId from the current request's vtex_segment cookie.
- * Returns null when no cookie provider is registered or no regionId is set.
+ * Returns null when outside a request context or no regionId is set.
  */
 function extractRegionIdFromCookies(): string | null {
-	if (!_getCookieHeader) return null;
-	const cookies = _getCookieHeader();
+	const ctx = RequestContext.current;
+	if (!ctx) return null;
+	const cookies = ctx.request.headers.get("cookie");
 	if (!cookies) return null;
 	const match = cookies.match(new RegExp(`(?:^|;\\s*)${SEGMENT_COOKIE_NAME}=([^;]+)`));
 	if (!match?.[1]) return null;
@@ -240,56 +228,43 @@ export async function vtexCachedFetch<T>(
 }
 
 /**
- * Result type for actions that need to propagate VTEX Set-Cookie headers.
- * In TanStack Start, the caller (server function) is responsible for
- * forwarding these cookies to the client via `setCookie` from vinxi/http.
- */
-export interface VtexFetchResult<T> {
-	data: T;
-	setCookies: string[];
-}
-
-/**
- * Like vtexFetch, but also returns Set-Cookie headers from the response.
+ * Like vtexFetch, but also forwards Set-Cookie headers via RequestContext.
  * Use for checkout, session, and auth actions that set cookies.
+ *
+ * Cookie propagation happens automatically:
+ * - Reads the browser's Cookie header from RequestContext.request
+ * - Writes upstream Set-Cookie headers to RequestContext.responseHeaders
+ * - The invoke handler copies responseHeaders into the HTTP Response
+ *
+ * This mirrors deco-cx/deco's `proxySetCookie(response.headers, ctx.response.headers)`.
  */
-export async function vtexFetchWithCookies<T>(
-	path: string,
-	init?: RequestInit,
-): Promise<VtexFetchResult<T>> {
-	// Auto-inject request cookies when no explicit cookie header is set
-	if (_getCookieHeader) {
-		const existingHeaders = init?.headers as Record<string, string> | undefined;
-		if (!existingHeaders?.["cookie"]) {
-			const cookies = _getCookieHeader();
-			if (cookies) {
-				init = {
-					...init,
-					headers: { ...existingHeaders, cookie: cookies },
-				};
-			}
+export async function vtexFetchWithCookies<T>(path: string, init?: RequestInit): Promise<T> {
+	// Auto-inject request cookies from RequestContext
+	const existingHeaders = init?.headers as Record<string, string> | undefined;
+	if (!existingHeaders?.["cookie"]) {
+		const ctx = RequestContext.current;
+		const cookies = ctx?.request.headers.get("cookie");
+		if (cookies) {
+			init = { ...init, headers: { ...existingHeaders, cookie: cookies } };
 		}
 	}
 
 	const response = await vtexFetchResponse(path, init);
 	const data = (await response.json()) as T;
-	const setCookies: string[] = [];
-	if (typeof response.headers.getSetCookie === "function") {
-		setCookies.push(...response.headers.getSetCookie());
-	} else {
-		response.headers.forEach((value, key) => {
-			if (key.toLowerCase() === "set-cookie") {
-				setCookies.push(value);
-			}
-		});
-	}
 
-	// Auto-forward Set-Cookie headers to the browser response
-	if (_forwardSetCookies && setCookies.length) {
-		_forwardSetCookies(setCookies);
+	// Forward Set-Cookie headers to RequestContext.responseHeaders
+	// (mirrors proxySetCookie from deco-cx/deco)
+	const responseHeaders = getResponseHeaders();
+	if (responseHeaders) {
+		const setCookies =
+			typeof response.headers.getSetCookie === "function" ? response.headers.getSetCookie() : [];
+		for (const cookie of setCookies) {
+			const stripped = cookie.replace(/;\s*domain=[^;]*/gi, "");
+			responseHeaders.append("set-cookie", stripped);
+		}
 	}
 
-	return { data, setCookies };
+	return data;
 }
 
 export async function intelligentSearch<T>(

package/vtex/index.ts

@@ -1,6 +1,6 @@
 /**
  * VTEX app entry point for @decocms/apps.
- * Re-exports client config + initializer.
+ * Re-exports client config + initializer + app contract.
  *
  * For actions/loaders/utils, use sub-path imports:
  *   import { addItemsToCart } from "@decocms/apps/vtex/actions/checkout"
@@ -12,3 +12,4 @@
  *   import { searchProducts }  from "@decocms/apps/vtex/loaders"
  */
 export * from "./client";
+export { configure, type VtexState } from "./mod";

package/vtex/manifest.gen.ts

@@ -0,0 +1,75 @@
+// 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_address from "./actions/address";
+import * as actions_auth from "./actions/auth";
+import * as actions_checkout from "./actions/checkout";
+import * as actions_masterData from "./actions/masterData";
+import * as actions_misc from "./actions/misc";
+import * as actions_newsletter from "./actions/newsletter";
+import * as actions_orders from "./actions/orders";
+import * as actions_profile from "./actions/profile";
+import * as actions_session from "./actions/session";
+import * as actions_trigger from "./actions/trigger";
+import * as actions_wishlist from "./actions/wishlist";
+import * as loaders_address from "./loaders/address";
+import * as loaders_brands from "./loaders/brands";
+import * as loaders_cart from "./loaders/cart";
+import * as loaders_catalog from "./loaders/catalog";
+import * as loaders_collections from "./loaders/collections";
+import * as loaders_legacy from "./loaders/legacy";
+import * as loaders_logistics from "./loaders/logistics";
+import * as loaders_navbar from "./loaders/navbar";
+import * as loaders_orders from "./loaders/orders";
+import * as loaders_pageType from "./loaders/pageType";
+import * as loaders_payment from "./loaders/payment";
+import * as loaders_profile from "./loaders/profile";
+import * as loaders_promotion from "./loaders/promotion";
+import * as loaders_search from "./loaders/search";
+import * as loaders_session from "./loaders/session";
+import * as loaders_user from "./loaders/user";
+import * as loaders_wishlist from "./loaders/wishlist";
+import * as loaders_wishlistProducts from "./loaders/wishlistProducts";
+import * as loaders_workflow from "./loaders/workflow";
+
+const manifest = {
+	name: "vtex",
+	loaders: {
+		"vtex/loaders/address": loaders_address,
+		"vtex/loaders/brands": loaders_brands,
+		"vtex/loaders/cart": loaders_cart,
+		"vtex/loaders/catalog": loaders_catalog,
+		"vtex/loaders/collections": loaders_collections,
+		"vtex/loaders/legacy": loaders_legacy,
+		"vtex/loaders/logistics": loaders_logistics,
+		"vtex/loaders/navbar": loaders_navbar,
+		"vtex/loaders/orders": loaders_orders,
+		"vtex/loaders/pageType": loaders_pageType,
+		"vtex/loaders/payment": loaders_payment,
+		"vtex/loaders/profile": loaders_profile,
+		"vtex/loaders/promotion": loaders_promotion,
+		"vtex/loaders/search": loaders_search,
+		"vtex/loaders/session": loaders_session,
+		"vtex/loaders/user": loaders_user,
+		"vtex/loaders/wishlist": loaders_wishlist,
+		"vtex/loaders/wishlistProducts": loaders_wishlistProducts,
+		"vtex/loaders/workflow": loaders_workflow,
+	},
+	actions: {
+		"vtex/actions/address": actions_address,
+		"vtex/actions/auth": actions_auth,
+		"vtex/actions/checkout": actions_checkout,
+		"vtex/actions/masterData": actions_masterData,
+		"vtex/actions/misc": actions_misc,
+		"vtex/actions/newsletter": actions_newsletter,
+		"vtex/actions/orders": actions_orders,
+		"vtex/actions/profile": actions_profile,
+		"vtex/actions/session": actions_session,
+		"vtex/actions/trigger": actions_trigger,
+		"vtex/actions/wishlist": actions_wishlist,
+	},
+	sections: {},
+} as const;
+
+export type Manifest = typeof manifest;
+export default manifest;

package/vtex/mod.ts

@@ -0,0 +1,83 @@
+/**
+ * VTEX app module — standard autoconfig contract.
+ *
+ * Exports `configure` following the AppModContract pattern.
+ * The framework's `autoconfigApps()` calls these generically.
+ *
+ * @example
+ * ```ts
+ * import * as vtexApp from "@decocms/apps/vtex/mod";
+ *
+ * const app = await vtexApp.configure(blocks.vtex, resolveSecret);
+ * if (app) {
+ *   // app.manifest, app.state, app.middleware are available
+ * }
+ * ```
+ */
+
+import type { AppDefinition, AppMiddleware, ResolveSecretFn } from "../commerce/app-types";
+import { configureVtex, type VtexConfig } from "./client";
+import manifest from "./manifest.gen";
+import { extractVtexContext, propagateISCookies, vtexCacheControl } from "./middleware";
+
+// -------------------------------------------------------------------------
+// State
+// -------------------------------------------------------------------------
+
+export interface VtexState {
+	config: VtexConfig;
+}
+
+// -------------------------------------------------------------------------
+// Middleware
+// -------------------------------------------------------------------------
+
+const vtexMiddleware: AppMiddleware = async (request, next) => {
+	const ctx = extractVtexContext(request);
+	const response = await next();
+	response.headers.set("Cache-Control", vtexCacheControl(ctx));
+	propagateISCookies(ctx, response);
+	return response;
+};
+
+// -------------------------------------------------------------------------
+// Configure
+// -------------------------------------------------------------------------
+
+/**
+ * Configure the VTEX 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<VtexState> | null> {
+	if (!block?.account) return null;
+
+	const appKey = await resolveSecret(block.appKey, "VTEX_APP_KEY");
+	const appToken = await resolveSecret(block.appToken, "VTEX_APP_TOKEN");
+
+	const config: VtexConfig = {
+		account: block.account,
+		publicUrl: block.publicUrl,
+		salesChannel: block.salesChannel || "1",
+		locale: block.locale || block.defaultLocale,
+		appKey: appKey ?? undefined,
+		appToken: appToken ?? undefined,
+		country: block.country,
+		domain: block.domain,
+	};
+
+	// Bridge: maintain global singleton for backward compat
+	configureVtex(config);
+
+	return {
+		name: "vtex",
+		manifest,
+		state: { config },
+		middleware: vtexMiddleware,
+	};
+}
+
+/** Placeholder preview for CMS editor — evolves when admin supports it. */
+export const preview = undefined;