@decocms/apps-vtex 7.2.0

package/src/loaders/workflow.ts

@@ -0,0 +1,316 @@
+/**
+ * VTEX Workflow loaders (internal/back-office use).
+ * These transform raw VTEX Catalog data into schema.org-compatible Product types.
+ * NOT intended for storefront rendering — used in data pipelines and workflows.
+ *
+ * Pure async functions — require configureVtex() to have been called.
+ *
+ * Ported from deco-cx/apps:
+ *   vtex/loaders/workflow/product.ts
+ *   vtex/loaders/workflow/products.ts
+ *
+ * @see https://developers.vtex.com/docs/api-reference/catalog-api
+ */
+import type {
+	Offer,
+	Product,
+	PropertyValue,
+	UnitPriceSpecification,
+} from "@decocms/apps-commerce/types";
+import { vtexFetch } from "../client";
+import {
+	aggregateOffers,
+	toAdditionalPropertyCategory,
+	toAdditionalPropertyCluster,
+	toAdditionalPropertyReferenceId,
+	toAdditionalPropertySpecification,
+} from "../utils/transform";
+
+/** VTEX prices come in cents — divide by this to get the currency value. */
+const CENTS_DIVISOR = 100;
+
+// ---------------------------------------------------------------------------
+// Types for pvt Catalog APIs
+// ---------------------------------------------------------------------------
+
+interface SkuImage {
+	ImageUrl: string;
+	ImageName?: string;
+	FileId?: string;
+}
+
+interface SkuSpecification {
+	FieldName: string;
+	FieldValues: string[];
+	FieldValueIds: number[];
+}
+
+interface SkuSeller {
+	SellerId: string;
+}
+
+interface SkuAlternateIds {
+	RefId?: string;
+	Ean?: string;
+}
+
+interface PvtSku {
+	Id: number;
+	ProductId: number;
+	IsActive: boolean;
+	SkuName: string;
+	ProductName: string;
+	ProductDescription: string;
+	DetailUrl: string;
+	BrandId: string;
+	BrandName: string;
+	ReleaseDate?: string;
+	Images: SkuImage[];
+	SkuSpecifications: SkuSpecification[];
+	ProductSpecifications: SkuSpecification[];
+	ProductCategories: Record<string, string>;
+	ProductClusterNames: Record<string, string>;
+	SalesChannels: number[];
+	AlternateIds: SkuAlternateIds;
+	SkuSellers: SkuSeller[];
+}
+
+interface PvtSkuListItem {
+	Id: number;
+	IsActive: boolean;
+}
+
+interface SalesChannel {
+	Id: number;
+	CurrencyCode: string;
+}
+
+interface SimulationItem {
+	sellingPrice: number;
+	listPrice: number;
+	price: number;
+	seller: string;
+	priceValidUntil: string;
+	availability: string;
+}
+
+interface SimulationPaymentOption {
+	paymentName: string;
+	installments: Array<{ count: number; value: number; total: number }>;
+}
+
+interface SimulationResponse {
+	items?: SimulationItem[];
+	paymentData?: { installmentOptions?: SimulationPaymentOption[] };
+}
+
+// ---------------------------------------------------------------------------
+// workflowProduct
+// ---------------------------------------------------------------------------
+
+export interface WorkflowProductOptions {
+	/** The SKU ID (stockKeepingUnitId) to load */
+	productID: string;
+	/** Sales channel for simulation. Defaults to 1. */
+	salesChannel?: number;
+}
+
+/**
+ * Transform a single VTEX SKU (via private Catalog API) into a commerce Product.
+ *
+ * Fetches the SKU details, all sibling SKUs for the same product, sales channels,
+ * and runs checkout simulation for each seller to build offer data.
+ *
+ * Ported from: vtex/loaders/workflow/product.ts
+ */
+export async function workflowProduct(opts: WorkflowProductOptions): Promise<Product | null> {
+	const sc = opts.salesChannel ?? 1;
+
+	const sku = await vtexFetch<PvtSku>(
+		`/api/catalog_system/pvt/sku/stockkeepingunitbyid/${opts.productID}`,
+	);
+
+	if (!sku.IsActive) return null;
+
+	const [skus, salesChannels, ...simulations] = await Promise.all([
+		vtexFetch<PvtSkuListItem[]>(
+			`/api/catalog_system/pvt/sku/stockkeepingunitByProductId/${sku.ProductId}`,
+		),
+		vtexFetch<SalesChannel[]>("/api/catalog_system/pvt/saleschannel/list"),
+		...sku.SkuSellers.map(({ SellerId }) =>
+			vtexFetch<SimulationResponse>(
+				`/api/checkout/pub/orderForms/simulation?RnbBehavior=1&sc=${sc}`,
+				{
+					method: "POST",
+					body: JSON.stringify({
+						items: [{ id: `${sku.Id}`, seller: SellerId, quantity: 1 }],
+					}),
+				},
+			),
+		),
+	]);
+
+	const channel = salesChannels.find((c) => c.Id === sc);
+	const productGroupID = `${sku.ProductId}`;
+	const productID = `${sku.Id}`;
+
+	const additionalProperty = [
+		sku.AlternateIds.RefId
+			? toAdditionalPropertyReferenceId({
+					name: "RefId",
+					value: sku.AlternateIds.RefId,
+				})
+			: null,
+		...Object.entries(sku.ProductCategories ?? {}).map(([propertyID, value]) =>
+			toAdditionalPropertyCategory({ propertyID, value }),
+		),
+		...Object.entries(sku.ProductClusterNames ?? {}).map(([propertyID, value]) =>
+			toAdditionalPropertyCluster({ propertyID, value }),
+		),
+		...sku.SkuSpecifications.flatMap((spec) =>
+			spec.FieldValues.map((value, it) =>
+				toAdditionalPropertySpecification({
+					propertyID: spec.FieldValueIds[it]?.toString(),
+					name: spec.FieldName,
+					value,
+				}),
+			),
+		),
+		...sku.SalesChannels.map(
+			(ch): PropertyValue => ({
+				"@type": "PropertyValue",
+				name: "salesChannel",
+				propertyID: ch.toString(),
+			}),
+		),
+	].filter((p): p is PropertyValue => Boolean(p));
+
+	const groupAdditionalProperty = sku.ProductSpecifications.flatMap((spec) =>
+		spec.FieldValues.map((value, it) =>
+			toAdditionalPropertySpecification({
+				propertyID: spec.FieldValueIds[it]?.toString(),
+				name: spec.FieldName,
+				value,
+			}),
+		),
+	);
+
+	const offers = simulations
+		.flatMap(({ items, paymentData }) =>
+			items?.map((item): Offer | null => {
+				const { sellingPrice, listPrice, price, seller, priceValidUntil, availability } = item;
+				const spotPrice = sellingPrice || price;
+				if (!spotPrice || !listPrice) return null;
+
+				return {
+					"@type": "Offer",
+					price: spotPrice / CENTS_DIVISOR,
+					seller,
+					priceValidUntil,
+					inventoryLevel: {},
+					availability:
+						availability === "available"
+							? "https://schema.org/InStock"
+							: "https://schema.org/OutOfStock",
+					priceSpecification: [
+						{
+							"@type": "UnitPriceSpecification",
+							priceType: "https://schema.org/ListPrice",
+							price: listPrice / CENTS_DIVISOR,
+						},
+						{
+							"@type": "UnitPriceSpecification",
+							priceType: "https://schema.org/SalePrice",
+							price: spotPrice / CENTS_DIVISOR,
+						},
+						...(paymentData?.installmentOptions?.flatMap((option): UnitPriceSpecification[] =>
+							option.installments.map((i) => ({
+								"@type": "UnitPriceSpecification",
+								priceType: "https://schema.org/SalePrice",
+								priceComponentType: "https://schema.org/Installment",
+								name: option.paymentName,
+								billingDuration: i.count,
+								billingIncrement: i.value / CENTS_DIVISOR,
+								price: i.total / CENTS_DIVISOR,
+							})),
+						) ?? []),
+					],
+				};
+			}),
+		)
+		.filter((o): o is Offer => Boolean(o));
+
+	return {
+		"@type": "Product",
+		productID,
+		sku: productID,
+		inProductGroupWithID: productGroupID,
+		category: Object.values(sku.ProductCategories ?? {}).join(" > "),
+		url: `${sku.DetailUrl}?skuId=${productID}`,
+		name: sku.SkuName,
+		gtin: sku.AlternateIds.Ean,
+		image: sku.Images.map((img) => ({
+			"@type": "ImageObject",
+			encodingFormat: "image",
+			alternateName: img.ImageName ?? img.FileId,
+			url: img.ImageUrl,
+		})),
+		isVariantOf: {
+			"@type": "ProductGroup",
+			url: sku.DetailUrl,
+			hasVariant:
+				skus
+					?.filter((x) => x.IsActive)
+					.map(({ Id }) => ({
+						"@type": "Product",
+						productID: `${Id}`,
+						sku: `${Id}`,
+					})) ?? [],
+			additionalProperty: groupAdditionalProperty,
+			productGroupID,
+			name: sku.ProductName,
+			description: sku.ProductDescription,
+		},
+		additionalProperty,
+		releaseDate: sku.ReleaseDate ? new Date(sku.ReleaseDate).toISOString() : undefined,
+		brand: {
+			"@type": "Brand",
+			"@id": sku.BrandId,
+			name: sku.BrandName,
+		},
+		offers: aggregateOffers(offers, channel?.CurrencyCode),
+	};
+}
+
+// ---------------------------------------------------------------------------
+// workflowProducts
+// ---------------------------------------------------------------------------
+
+export interface WorkflowProductsOptions {
+	page: number;
+	pagesize: number;
+}
+
+/**
+ * Fetch a page of SKU IDs and return minimal Product stubs.
+ * Use in batch workflows to enumerate the catalog; call workflowProduct
+ * for each ID if full details are needed.
+ *
+ * Ported from: vtex/loaders/workflow/products.ts
+ */
+export async function workflowProducts(opts: WorkflowProductsOptions): Promise<Product[]> {
+	const params = new URLSearchParams({
+		page: String(opts.page),
+		pagesize: String(opts.pagesize),
+	});
+
+	const ids = await vtexFetch<number[]>(
+		`/api/catalog_system/pvt/sku/stockkeepingunitids?${params}`,
+	);
+
+	return ids.map((productID) => ({
+		"@type": "Product",
+		productID: `${productID}`,
+		sku: `${productID}`,
+	}));
+}

package/src/middleware.ts

@@ -0,0 +1,240 @@
+/**
+ * VTEX Middleware utilities for TanStack Start.
+ *
+ * Extracts segment information from cookies/URL params, detects login state,
+ * propagates Intelligent Search cookies, and provides cache-control decisions.
+ *
+ * Use with TanStack Start's createMiddleware() in the storefront:
+ *
+ * @example
+ * ```ts
+ * import { createMiddleware } from "@tanstack/react-start";
+ * import {
+ *   extractVtexContext,
+ *   vtexCacheControl,
+ * } from "@decocms/apps/vtex/middleware";
+ *
+ * const vtexMiddleware = createMiddleware().server(async ({ next, request }) => {
+ *   const vtexCtx = extractVtexContext(request);
+ *   const response = await next();
+ *   response.headers.set("Cache-Control", vtexCacheControl(vtexCtx));
+ *   propagateISCookies(request, response);
+ *   return response;
+ * });
+ * ```
+ */
+
+import { ANONYMOUS_COOKIE, SESSION_COOKIE } from "./utils/intelligentSearch";
+import {
+	buildSegmentFromParams,
+	DEFAULT_SEGMENT,
+	parseSegment,
+	SALES_CHANNEL_COOKIE,
+	SEGMENT_COOKIE_NAME,
+	serializeSegment,
+} from "./utils/segment";
+import type { Segment } from "./utils/types";
+import { extractVtexAuthCookie, parseVtexAuthToken } from "./utils/vtexId";
+
+// -------------------------------------------------------------------------
+// Types
+// -------------------------------------------------------------------------
+
+export interface VtexRequestContext {
+	/** Decoded segment from cookie or URL params. */
+	segment: Partial<Segment>;
+	/** Serialized segment token for cache key use. */
+	segmentToken: string;
+	/** Whether the user has a valid (non-expired) VTEX auth cookie. */
+	isLoggedIn: boolean;
+	/** Extracted email from the auth JWT, if available. */
+	email?: string;
+	/** Sales channel derived from segment. */
+	salesChannel: string;
+	/**
+	 * VTEX region ID from the segment cookie.
+	 * Present when the user has set a postal code (CEP) for regionalization.
+	 * Null when no region is set (anonymous default segment).
+	 */
+	regionId: string | null;
+	/** Whether this request carries price tables (B2B). */
+	hasCustomPricing: boolean;
+	/** Intelligent Search session cookie. */
+	isSessionId: string;
+	/** Intelligent Search anonymous cookie. */
+	isAnonymousId: string;
+	/** Whether IS cookies were freshly generated (browser didn't send them). */
+	needsISCookies: boolean;
+}
+
+// -------------------------------------------------------------------------
+// Cookie helpers
+// -------------------------------------------------------------------------
+
+const _IS_COOKIE_PREFIX = "vtex_is_";
+
+/** Seconds in one day (86 400). Used for cookie Max-Age and stale-if-error. */
+const ONE_DAY_SECONDS = 86_400;
+
+/** Seconds in one year (~365 days). Used for long-lived IS cookie Max-Age. */
+const ONE_YEAR_SECONDS = 365 * 24 * 60 * 60;
+
+function getCookieValue(cookieHeader: string, name: string): string | null {
+	const match = cookieHeader.match(new RegExp(`(?:^|;\\s*)${name}=([^;]+)`));
+	return match?.[1] ?? null;
+}
+
+// -------------------------------------------------------------------------
+// Core extraction
+// -------------------------------------------------------------------------
+
+/**
+ * Extract VTEX context from an incoming request.
+ *
+ * Reads the segment cookie, URL params (utm_*, sc), and auth cookie
+ * to build a complete picture of the user's VTEX session state.
+ */
+function generateUUID(): string {
+	if (typeof crypto !== "undefined" && crypto.randomUUID) {
+		return crypto.randomUUID();
+	}
+	return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+		const r = (Math.random() * 16) | 0;
+		return (c === "x" ? r : (r & 0x3) | 0x8).toString(16);
+	});
+}
+
+export function extractVtexContext(request: Request): VtexRequestContext {
+	const cookies = request.headers.get("cookie") ?? "";
+	const url = new URL(request.url);
+
+	const segmentCookie = getCookieValue(cookies, SEGMENT_COOKIE_NAME);
+	const cookieSegment = segmentCookie ? parseSegment(segmentCookie) : null;
+
+	const paramSegment = buildSegmentFromParams(url.searchParams);
+
+	const vtexsc = getCookieValue(cookies, SALES_CHANNEL_COOKIE);
+
+	const segment: Partial<Segment> = {
+		...DEFAULT_SEGMENT,
+		...cookieSegment,
+		...paramSegment,
+	};
+	if (vtexsc) segment.channel = vtexsc;
+
+	const segmentToken = serializeSegment(segment);
+
+	const authToken = extractVtexAuthCookie(cookies);
+	const authInfo = authToken ? parseVtexAuthToken(authToken) : null;
+
+	const existingSessionId = getCookieValue(cookies, SESSION_COOKIE);
+	const existingAnonymousId = getCookieValue(cookies, ANONYMOUS_COOKIE);
+	const needsISCookies = !existingSessionId || !existingAnonymousId;
+
+	return {
+		segment,
+		segmentToken,
+		isLoggedIn: authInfo?.isLoggedIn ?? false,
+		email: authInfo?.email,
+		salesChannel: segment.channel ?? "1",
+		regionId: segment.regionId ?? null,
+		hasCustomPricing: Boolean(segment.priceTables && segment.priceTables.length > 0),
+		isSessionId: existingSessionId ?? generateUUID(),
+		isAnonymousId: existingAnonymousId ?? generateUUID(),
+		needsISCookies,
+	};
+}
+
+// -------------------------------------------------------------------------
+// Cache control
+// -------------------------------------------------------------------------
+
+/**
+ * Determine the appropriate Cache-Control header based on VTEX context.
+ *
+ * Rules:
+ * - Logged-in users: private (personalized prices, wishlists, etc.)
+ * - Custom pricing (B2B): private (price table specific)
+ * - Anonymous default segment: public with CDN caching
+ */
+export function vtexCacheControl(
+	ctx: VtexRequestContext,
+	options?: {
+		/** Max age for public (anonymous) responses in seconds. @default 60 */
+		publicMaxAge?: number;
+		/** Stale-while-revalidate for public responses in seconds. @default 3600 */
+		publicSWR?: number;
+	},
+): string {
+	if (ctx.isLoggedIn || ctx.hasCustomPricing) {
+		return "private, no-cache, no-store, must-revalidate";
+	}
+
+	const maxAge = options?.publicMaxAge ?? 60;
+	const swr = options?.publicSWR ?? 3600;
+
+	return `public, s-maxage=${maxAge}, stale-while-revalidate=${swr}, stale-if-error=${ONE_DAY_SECONDS}`;
+}
+
+// -------------------------------------------------------------------------
+// Cookie propagation
+// -------------------------------------------------------------------------
+
+/**
+ * Set Intelligent Search cookies on the response only when the browser
+ * doesn't already have them. On subsequent requests where the cookies
+ * exist, this is a no-op — keeping the response free of Set-Cookie
+ * headers so it remains cacheable at the CDN edge.
+ */
+export function propagateISCookies(ctx: VtexRequestContext, response: Response): void {
+	if (!ctx.needsISCookies) return;
+
+	const maxAge = ONE_YEAR_SECONDS;
+	response.headers.append(
+		"Set-Cookie",
+		`${SESSION_COOKIE}=${ctx.isSessionId}; Path=/; SameSite=Lax; Max-Age=${maxAge}`,
+	);
+	response.headers.append(
+		"Set-Cookie",
+		`${ANONYMOUS_COOKIE}=${ctx.isAnonymousId}; Path=/; SameSite=Lax; Max-Age=${maxAge}`,
+	);
+}
+
+/**
+ * Build a segment cookie Set-Cookie header for the response.
+ *
+ * Use this when URL params change the segment (e.g., ?sc=2) so the
+ * browser persists the new segment for subsequent requests.
+ */
+export function buildSegmentSetCookie(segment: Partial<Segment>, domain?: string): string {
+	const token = serializeSegment(segment);
+	let cookie = `${SEGMENT_COOKIE_NAME}=${token}; Path=/; SameSite=Lax; Max-Age=${ONE_DAY_SECONDS}`;
+	if (domain) cookie += `; Domain=${domain}`;
+	return cookie;
+}
+
+// -------------------------------------------------------------------------
+// Cache key helpers
+// -------------------------------------------------------------------------
+
+/**
+ * Build a cache key suffix from the VTEX context.
+ *
+ * This is used in the Cloudflare Worker entry to differentiate cached
+ * responses by segment. Two anonymous users on the same sales channel
+ * get the same cache key; a logged-in user gets a unique (uncached) key.
+ */
+export function vtexCacheKeySuffix(ctx: VtexRequestContext): string {
+	if (ctx.isLoggedIn) return "__vtex_auth";
+	const parts = [`sc=${ctx.salesChannel}`];
+	if (ctx.regionId) parts.push(`r=${ctx.regionId}`);
+	return `__vtex_${parts.join("_")}`;
+}
+
+// -------------------------------------------------------------------------
+// Re-exports for convenience
+// -------------------------------------------------------------------------
+
+export type { Segment } from "./utils/types";
+export type { VtexAuthInfo } from "./utils/vtexId";
+export { isVtexLoggedIn } from "./utils/vtexId";

package/src/mod.ts

@@ -0,0 +1,152 @@
+/**
+ * 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 "@decocms/apps-commerce/app-types";
+import type { Secret } from "@decocms/apps-website/mod";
+import { configureVtex, type VtexConfig } from "./client";
+import manifest from "./manifest.gen";
+import { extractVtexContext, propagateISCookies, vtexCacheControl } from "./middleware";
+
+// -------------------------------------------------------------------------
+// CMS Props (mirrors deco-cx/apps/vtex/mod.ts)
+// -------------------------------------------------------------------------
+
+/** @title VTEX */
+export interface Props {
+	/**
+	 * @description VTEX Account name
+	 */
+	account: string;
+
+	/**
+	 * @title Public store URL
+	 * @description Domain registered on License Manager (e.g. secure.mystore.com.br)
+	 */
+	publicUrl: string;
+
+	/** @title App Key */
+	appKey?: Secret;
+
+	/**
+	 * @title App Token
+	 * @format password
+	 */
+	appToken?: Secret;
+
+	/**
+	 * @title Default Sales Channel
+	 * @deprecated
+	 */
+	salesChannel?: string;
+
+	/**
+	 * @title Set Refresh Token
+	 * @default false
+	 */
+	setRefreshToken?: boolean;
+
+	defaultSegment?: Record<string, unknown>;
+
+	usePortalSitemap?: boolean;
+
+	/**
+	 * @hide true
+	 * @default vtex
+	 */
+	platform?: "vtex";
+
+	advancedConfigs?: {
+		doNotFetchVariantsForRelatedProducts?: boolean;
+		removeUTMFromCacheKey?: boolean;
+	};
+
+	/** @title Cached Search Terms */
+	cachedSearchTerms?: {
+		terms?: unknown;
+		extraTerms?: string[];
+	};
+}
+
+export type { Secret };
+
+// -------------------------------------------------------------------------
+// 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(
+	// biome-ignore lint/suspicious/noExplicitAny: block data comes from CMS with no fixed schema
+	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;
+
+/** Default export for schema generation and Deno-style app bridges. */
+export default function VTEX(_props: Props) {
+	return { state: _props };
+}