@decocms/apps 0.20.1

package/vtex/loaders/workflow.ts

@@ -0,0 +1,323 @@
+/**
+ * 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 "../../commerce/types/commerce";
+import { vtexFetch } from "../client";
+import {
+  aggregateOffers,
+  toAdditionalPropertyCategory,
+  toAdditionalPropertyCluster,
+  toAdditionalPropertyReferenceId,
+  toAdditionalPropertySpecification,
+} from "../utils/transform";
+
+// ---------------------------------------------------------------------------
+// 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 / 100,
+          seller,
+          priceValidUntil,
+          inventoryLevel: {},
+          availability:
+            availability === "available"
+              ? "https://schema.org/InStock"
+              : "https://schema.org/OutOfStock",
+          priceSpecification: [
+            {
+              "@type": "UnitPriceSpecification",
+              priceType: "https://schema.org/ListPrice",
+              price: listPrice / 100,
+            },
+            {
+              "@type": "UnitPriceSpecification",
+              priceType: "https://schema.org/SalePrice",
+              price: spotPrice / 100,
+            },
+            ...(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 / 100,
+                  price: i.total / 100,
+                })),
+            ) ?? []),
+          ],
+        };
+      }),
+    )
+    .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/vtex/middleware.ts

@@ -0,0 +1,229 @@
+/**
+ * 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 {
+  SEGMENT_COOKIE_NAME,
+  SALES_CHANNEL_COOKIE,
+  parseSegment,
+  buildSegmentFromParams,
+  serializeSegment,
+  DEFAULT_SEGMENT,
+  type WrappedSegment,
+} from "./utils/segment";
+import { SESSION_COOKIE, ANONYMOUS_COOKIE } from "./utils/intelligentSearch";
+import { isVtexLoggedIn, extractVtexAuthCookie, parseVtexAuthToken } from "./utils/vtexId";
+import type { Segment } from "./utils/types";
+
+// -------------------------------------------------------------------------
+// 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;
+  /** Whether this request carries price tables (B2B). */
+  hasCustomPricing: boolean;
+  /** Intelligent Search session cookie. */
+  isSessionId: string;
+  /** Intelligent Search anonymous cookie. */
+  isAnonymousId: string;
+}
+
+// -------------------------------------------------------------------------
+// Cookie helpers
+// -------------------------------------------------------------------------
+
+const IS_COOKIE_PREFIX = "vtex_is_";
+
+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 isSessionId = getCookieValue(cookies, SESSION_COOKIE) ?? generateUUID();
+  const isAnonymousId = getCookieValue(cookies, ANONYMOUS_COOKIE) ?? generateUUID();
+
+  return {
+    segment,
+    segmentToken,
+    isLoggedIn: authInfo?.isLoggedIn ?? false,
+    email: authInfo?.email,
+    salesChannel: segment.channel ?? "1",
+    hasCustomPricing: Boolean(
+      segment.priceTables && segment.priceTables.length > 0,
+    ),
+    isSessionId,
+    isAnonymousId,
+  };
+}
+
+// -------------------------------------------------------------------------
+// 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=86400`;
+}
+
+// -------------------------------------------------------------------------
+// Cookie propagation
+// -------------------------------------------------------------------------
+
+/**
+ * Ensure Intelligent Search cookies exist on the response.
+ *
+ * If the browser already has them, they are forwarded as-is.
+ * If not, new UUIDs from the context are set. This ensures
+ * every user has IS cookies for personalization and analytics.
+ */
+export function propagateISCookies(
+  ctx: VtexRequestContext,
+  response: Response,
+): void {
+  const maxAge = 365 * 24 * 60 * 60;
+  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=86400`;
+  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";
+  return `__vtex_sc=${ctx.salesChannel}`;
+}
+
+// -------------------------------------------------------------------------
+// Re-exports for convenience
+// -------------------------------------------------------------------------
+
+export { isVtexLoggedIn } from "./utils/vtexId";
+export type { VtexAuthInfo } from "./utils/vtexId";
+export type { Segment } from "./utils/types";