@decocms/start 0.19.0

package/src/sdk/analytics.ts

@@ -0,0 +1,72 @@
+/**
+ * Analytics utilities using the data-event attribute pattern.
+ * Compatible with Deco's analytics pipeline and GTM.
+ */
+
+export interface DataEventParams {
+  on: "view" | "click" | "change";
+  event: { name: string; params?: Record<string, unknown> };
+}
+
+export function useSendEvent({ on, event }: DataEventParams) {
+  return {
+    "data-event": encodeURIComponent(JSON.stringify(event)),
+    "data-event-trigger": on,
+  };
+}
+
+/**
+ * Inline script that observes data-event attributes and dispatches events.
+ * Inject once in the root layout via a <script> tag.
+ */
+export const ANALYTICS_SCRIPT = `
+(function() {
+  function dispatch(event) {
+    if (window.dataLayer) {
+      window.dataLayer.push({ event: event.name, ...event.params });
+    }
+    if (window.DECO && window.DECO.events) {
+      window.DECO.events.dispatch(event);
+    }
+  }
+
+  function getEvent(el) {
+    var raw = el.getAttribute("data-event");
+    if (!raw) return null;
+    try { return JSON.parse(decodeURIComponent(raw)); } catch(e) { return null; }
+  }
+
+  var viewObserver = new IntersectionObserver(function(entries) {
+    entries.forEach(function(entry) {
+      if (entry.isIntersecting) {
+        var event = getEvent(entry.target);
+        if (event) dispatch(event);
+        viewObserver.unobserve(entry.target);
+      }
+    });
+  }, { threshold: 0.5 });
+
+  document.addEventListener("click", function(e) {
+    var el = e.target.closest("[data-event-trigger='click']");
+    if (el) {
+      var event = getEvent(el);
+      if (event) dispatch(event);
+    }
+  });
+
+  function observeAll() {
+    document.querySelectorAll("[data-event-trigger='view']").forEach(function(el) {
+      viewObserver.observe(el);
+    });
+  }
+
+  observeAll();
+  new MutationObserver(observeAll).observe(document.body, { childList: true, subtree: true });
+})();
+`;
+
+/** Returns a GTM container snippet. Returns empty string if no containerId. */
+export function gtmScript(containerId?: string): string {
+  if (!containerId) return "";
+  return `(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);})(window,document,'script','dataLayer','${containerId}');`;
+}

package/src/sdk/cacheHeaders.ts

@@ -0,0 +1,268 @@
+/**
+ * Cache-Control header generation for different page types.
+ *
+ * Produces spec-compliant `Cache-Control` values suitable for CDNs
+ * (Cloudflare, Vercel, Fastly) with `s-maxage` and `stale-while-revalidate`.
+ *
+ * @example
+ * ```ts
+ * // In a TanStack Start route:
+ * import { cacheHeaders, routeCacheDefaults } from "@decocms/start/sdk/cacheHeaders";
+ *
+ * export const Route = createFileRoute('/products/$slug')({
+ *   ...routeCacheDefaults("product"),
+ *   headers: () => cacheHeaders("product"),
+ * });
+ * ```
+ */
+
+export type CacheProfile =
+  | "static"
+  | "product"
+  | "listing"
+  | "search"
+  | "cart"
+  | "private"
+  | "none";
+
+export interface CacheHeadersConfig {
+  /** Browser max-age in seconds. */
+  maxAge: number;
+  /** CDN/edge max-age in seconds. */
+  sMaxAge: number;
+  /** Stale-while-revalidate window in seconds. */
+  staleWhileRevalidate: number;
+  /** Whether the response is public (cacheable by CDN). */
+  isPublic: boolean;
+}
+
+const PROFILES: Record<CacheProfile, CacheHeadersConfig> = {
+  static: {
+    maxAge: 120,
+    sMaxAge: 86400,
+    staleWhileRevalidate: 86400,
+    isPublic: true,
+  },
+  product: {
+    maxAge: 60,
+    sMaxAge: 300,
+    staleWhileRevalidate: 3600,
+    isPublic: true,
+  },
+  listing: {
+    maxAge: 30,
+    sMaxAge: 120,
+    staleWhileRevalidate: 600,
+    isPublic: true,
+  },
+  search: {
+    maxAge: 0,
+    sMaxAge: 60,
+    staleWhileRevalidate: 300,
+    isPublic: true,
+  },
+  cart: {
+    maxAge: 0,
+    sMaxAge: 0,
+    staleWhileRevalidate: 0,
+    isPublic: false,
+  },
+  private: {
+    maxAge: 0,
+    sMaxAge: 0,
+    staleWhileRevalidate: 0,
+    isPublic: false,
+  },
+  none: {
+    maxAge: 0,
+    sMaxAge: 0,
+    staleWhileRevalidate: 0,
+    isPublic: false,
+  },
+};
+
+/**
+ * Generate a `Cache-Control` header value from a named profile or custom config.
+ * Returns a headers object ready to spread into route `headers()`.
+ *
+ * Always includes `Vary: Accept-Encoding` for public responses.
+ */
+export function cacheHeaders(
+  profileOrConfig: CacheProfile | CacheHeadersConfig,
+): Record<string, string> {
+  const config = typeof profileOrConfig === "string" ? PROFILES[profileOrConfig] : profileOrConfig;
+
+  if (!config.isPublic || (config.sMaxAge === 0 && config.maxAge === 0)) {
+    return {
+      "Cache-Control": "private, no-cache, no-store, must-revalidate",
+    };
+  }
+
+  const parts: string[] = ["public"];
+
+  if (config.maxAge > 0) {
+    parts.push(`max-age=${config.maxAge}`);
+  } else {
+    parts.push("max-age=0");
+  }
+
+  if (config.sMaxAge > 0) {
+    parts.push(`s-maxage=${config.sMaxAge}`);
+  }
+
+  if (config.staleWhileRevalidate > 0) {
+    parts.push(`stale-while-revalidate=${config.staleWhileRevalidate}`);
+  }
+
+  return {
+    "Cache-Control": parts.join(", "),
+    Vary: "Accept-Encoding",
+  };
+}
+
+/**
+ * Get the raw config for a named cache profile.
+ * Useful when you need the numeric values (e.g. for custom logic).
+ */
+export function getCacheProfileConfig(profile: CacheProfile): CacheHeadersConfig {
+  return PROFILES[profile];
+}
+
+// ---------------------------------------------------------------------------
+// Client-side route cache defaults (TanStack Router staleTime / gcTime)
+// ---------------------------------------------------------------------------
+
+interface RouteCacheDefaults {
+  /** How long route data is considered fresh on the client (ms). */
+  staleTime: number;
+  /** How long stale data is kept in memory before garbage collection (ms). */
+  gcTime: number;
+}
+
+const ROUTE_CACHE: Record<CacheProfile, RouteCacheDefaults> = {
+  static: { staleTime: 5 * 60_000, gcTime: 30 * 60_000 },
+  product: { staleTime: 60_000, gcTime: 5 * 60_000 },
+  listing: { staleTime: 60_000, gcTime: 5 * 60_000 },
+  search: { staleTime: 30_000, gcTime: 2 * 60_000 },
+  cart: { staleTime: 0, gcTime: 0 },
+  private: { staleTime: 0, gcTime: 0 },
+  none: { staleTime: 0, gcTime: 0 },
+};
+
+/**
+ * Returns `{ staleTime, gcTime }` for a cache profile, ready to spread
+ * into a TanStack Router route definition.
+ *
+ * In dev mode, uses short staleTime (5s) to keep data fresh enough for
+ * development while avoiding redundant re-fetches during rapid
+ * interactions (e.g. variant switching on a PDP).
+ *
+ * @example
+ * ```ts
+ * export const Route = createFileRoute("/$")({
+ *   ...routeCacheDefaults("listing"),
+ *   loader: ...,
+ *   headers: () => cacheHeaders("listing"),
+ * });
+ * ```
+ */
+export function routeCacheDefaults(profile: CacheProfile): RouteCacheDefaults {
+  const env = typeof globalThis.process !== "undefined" ? globalThis.process.env : undefined;
+  const isDev = env?.DECO_CACHE_DISABLE === "true" || env?.NODE_ENV === "development";
+  if (isDev) return { staleTime: 5_000, gcTime: 30_000 };
+  return ROUTE_CACHE[profile];
+}
+
+// ---------------------------------------------------------------------------
+// URL-based cache profile detection
+// ---------------------------------------------------------------------------
+
+interface CachePattern {
+  test: (pathname: string, searchParams: URLSearchParams) => boolean;
+  profile: CacheProfile;
+}
+
+const builtinPatterns: CachePattern[] = [
+  // Private routes — must be first (highest priority)
+  {
+    test: (p) =>
+      p.startsWith("/cart") ||
+      p.startsWith("/checkout") ||
+      p.startsWith("/account") ||
+      p.startsWith("/login") ||
+      p.startsWith("/my-account"),
+    profile: "private",
+  },
+  // Internal / API routes
+  {
+    test: (p) =>
+      p.startsWith("/api/") ||
+      p.startsWith("/deco/") ||
+      p.startsWith("/_server") ||
+      p.startsWith("/_build"),
+    profile: "none",
+  },
+  // Search pages
+  {
+    test: (p, sp) => p === "/s" || p.startsWith("/s/") || sp.has("q"),
+    profile: "search",
+  },
+  // PDP — VTEX convention: URL ends with /p
+  {
+    test: (p) => p.endsWith("/p") || /\/p[?#]/.test(p),
+    profile: "product",
+  },
+  // Home page
+  {
+    test: (p) => p === "/" || p === "",
+    profile: "static",
+  },
+];
+
+const customPatterns: CachePattern[] = [];
+
+/**
+ * Register additional URL-to-profile patterns. Custom patterns are evaluated
+ * before built-in ones, so they can override defaults.
+ *
+ * @example
+ * ```ts
+ * registerCachePattern({
+ *   test: (p) => p.startsWith("/institucional"),
+ *   profile: "static",
+ * });
+ * ```
+ */
+export function registerCachePattern(pattern: CachePattern): void {
+  customPatterns.push(pattern);
+}
+
+/**
+ * Detect the appropriate cache profile based on a URL.
+ * Evaluates custom patterns first, then built-in patterns.
+ * Falls back to "listing" (conservative public cache) for unmatched paths.
+ */
+export function detectCacheProfile(pathnameOrUrl: string | URL): CacheProfile {
+  let pathname: string;
+  let searchParams: URLSearchParams;
+
+  if (typeof pathnameOrUrl === "string" && !pathnameOrUrl.startsWith("http")) {
+    const qIdx = pathnameOrUrl.indexOf("?");
+    pathname = qIdx >= 0 ? pathnameOrUrl.slice(0, qIdx) : pathnameOrUrl;
+    searchParams = new URLSearchParams(qIdx >= 0 ? pathnameOrUrl.slice(qIdx) : "");
+  } else {
+    const url = pathnameOrUrl instanceof URL ? pathnameOrUrl : new URL(pathnameOrUrl);
+    pathname = url.pathname;
+    searchParams = url.searchParams;
+  }
+
+  for (const pattern of customPatterns) {
+    if (pattern.test(pathname, searchParams)) return pattern.profile;
+  }
+  for (const pattern of builtinPatterns) {
+    if (pattern.test(pathname, searchParams)) return pattern.profile;
+  }
+
+  // Default: listing (conservative, short edge TTL)
+  return "listing";
+}

package/src/sdk/cachedLoader.ts

@@ -0,0 +1,206 @@
+/**
+ * Server-side loader caching with stale-while-revalidate semantics.
+ *
+ * This provides a lightweight in-memory cache layer for commerce loaders
+ * that runs on the server during SSR, without requiring TanStack Query
+ * (which is optional and operates at the client/route level).
+ *
+ * For client-side SWR, use TanStack Query's `staleTime` / `gcTime`.
+ */
+
+export type CachePolicy = "no-store" | "no-cache" | "stale-while-revalidate";
+
+export interface CachedLoaderOptions {
+  policy: CachePolicy;
+  /** Max age in milliseconds before an entry is considered stale. Default: 60_000 (1 min). */
+  maxAge?: number;
+  /** Key function to generate a cache key from loader props. Default: JSON.stringify. */
+  keyFn?: (props: unknown) => string;
+}
+
+/**
+ * Loader module interface for modules that export cache configuration alongside
+ * their default loader function. Mirrors deco-cx/apps pattern where loaders
+ * can declare their own caching policy.
+ *
+ * @example
+ * ```ts
+ * // In a loader file:
+ * export const cache = "stale-while-revalidate";
+ * export const cacheKey = (props: any) => `myLoader:${props.slug}`;
+ * export default async function myLoader(props: Props) { ... }
+ * ```
+ */
+export interface LoaderModule<TProps = any, TResult = any> {
+  default: (props: TProps) => Promise<TResult>;
+  cache?: CachePolicy | { maxAge: number };
+  cacheKey?: (props: TProps) => string | null;
+}
+
+interface CacheEntry<T = unknown> {
+  value: T;
+  createdAt: number;
+  refreshing: boolean;
+}
+
+const DEFAULT_MAX_AGE = 60_000;
+const MAX_CACHE_ENTRIES = 500;
+
+const cache = new Map<string, CacheEntry>();
+
+function evictIfNeeded() {
+  if (cache.size <= MAX_CACHE_ENTRIES) return;
+  const oldest = [...cache.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
+  const toDelete = oldest.slice(0, cache.size - MAX_CACHE_ENTRIES);
+  for (const [key] of toDelete) cache.delete(key);
+}
+
+const inflightRequests = new Map<string, Promise<unknown>>();
+
+/**
+ * Wraps a loader function with server-side caching and single-flight dedup.
+ *
+ * @example
+ * ```ts
+ * const cachedProductList = createCachedLoader(
+ *   "vtex/loaders/productList",
+ *   vtexProductList,
+ *   { policy: "stale-while-revalidate", maxAge: 30_000 }
+ * );
+ * ```
+ */
+export function createCachedLoader<TProps, TResult>(
+  name: string,
+  loaderFn: (props: TProps) => Promise<TResult>,
+  options: CachedLoaderOptions,
+): (props: TProps) => Promise<TResult> {
+  const { policy, maxAge = DEFAULT_MAX_AGE, keyFn = JSON.stringify } = options;
+
+  const env = typeof globalThis.process !== "undefined" ? globalThis.process.env : undefined;
+  const isDev = env?.DECO_CACHE_DISABLE === "true" || env?.NODE_ENV === "development";
+
+  if (policy === "no-store") return loaderFn;
+
+  return async (props: TProps): Promise<TResult> => {
+    const cacheKey = `${name}::${keyFn(props)}`;
+
+    // Single-flight dedup: if an identical request is already in-flight, reuse it
+    const inflight = inflightRequests.get(cacheKey);
+    if (inflight) return inflight as Promise<TResult>;
+
+    // In dev mode, skip SWR cache but keep inflight dedup
+    if (isDev) {
+      const promise = loaderFn(props).finally(() => inflightRequests.delete(cacheKey));
+      inflightRequests.set(cacheKey, promise);
+      return promise;
+    }
+
+    const entry = cache.get(cacheKey) as CacheEntry<TResult> | undefined;
+    const now = Date.now();
+    const isStale = entry ? now - entry.createdAt > maxAge : true;
+
+    if (policy === "no-cache") {
+      if (entry && !isStale) return entry.value;
+      // Stale or missing — fetch fresh
+    }
+
+    if (policy === "stale-while-revalidate") {
+      if (entry && !isStale) return entry.value;
+
+      if (entry && isStale && !entry.refreshing) {
+        entry.refreshing = true;
+        // Fire-and-forget background refresh
+        loaderFn(props)
+          .then((result) => {
+            cache.set(cacheKey, {
+              value: result,
+              createdAt: Date.now(),
+              refreshing: false,
+            });
+          })
+          .catch(() => {
+            entry.refreshing = false;
+          });
+        return entry.value;
+      }
+
+      if (entry) return entry.value;
+    }
+
+    const promise = loaderFn(props)
+      .then((result) => {
+        cache.set(cacheKey, {
+          value: result,
+          createdAt: Date.now(),
+          refreshing: false,
+        });
+        evictIfNeeded();
+        inflightRequests.delete(cacheKey);
+        return result;
+      })
+      .catch((err) => {
+        inflightRequests.delete(cacheKey);
+        throw err;
+      });
+
+    inflightRequests.set(cacheKey, promise);
+    return promise;
+  };
+}
+
+/**
+ * Create a cached loader from a module that exports `cache` and/or `cacheKey`.
+ * Falls back to the provided defaults if the module doesn't declare them.
+ *
+ * @example
+ * ```ts
+ * import * as myLoaderModule from "./loaders/myLoader";
+ * const cached = createCachedLoaderFromModule("myLoader", myLoaderModule, {
+ *   policy: "stale-while-revalidate",
+ *   maxAge: 60_000,
+ * });
+ * ```
+ */
+export function createCachedLoaderFromModule<TProps, TResult>(
+  name: string,
+  mod: LoaderModule<TProps, TResult>,
+  defaults?: Partial<CachedLoaderOptions>,
+): (props: TProps) => Promise<TResult> {
+  const moduleCache = mod.cache;
+  let policy: CachePolicy;
+  let maxAge: number | undefined;
+
+  if (typeof moduleCache === "string") {
+    policy = moduleCache;
+  } else if (moduleCache && typeof moduleCache === "object") {
+    policy = "stale-while-revalidate";
+    maxAge = moduleCache.maxAge;
+  } else {
+    policy = defaults?.policy ?? "stale-while-revalidate";
+  }
+
+  maxAge = maxAge ?? defaults?.maxAge;
+
+  const keyFn = mod.cacheKey
+    ? (props: unknown) => {
+        const key = mod.cacheKey!(props as TProps);
+        return key ?? JSON.stringify(props);
+      }
+    : defaults?.keyFn;
+
+  return createCachedLoader(name, mod.default, { policy, maxAge, keyFn });
+}
+
+/** Clear all cached entries. Useful for decofile hot-reload. */
+export function clearLoaderCache() {
+  cache.clear();
+  inflightRequests.clear();
+}
+
+/** Get cache stats for diagnostics. */
+export function getLoaderCacheStats() {
+  return {
+    entries: cache.size,
+    inflight: inflightRequests.size,
+  };
+}

package/src/sdk/clx.ts

@@ -0,0 +1,3 @@
+/** Filter out nullable values, join and minify class names */
+export const clx = (...args: (string | null | undefined | false)[]) =>
+  args.filter(Boolean).join(" ").replace(/\s\s+/g, " ");

package/src/sdk/cookie.ts

@@ -0,0 +1,39 @@
+export function getCookie(name: string): string {
+  return (
+    globalThis.window?.document?.cookie?.split("; ").reduce((r, v) => {
+      const parts = v.split("=");
+      return parts[0] === name ? decodeURIComponent(parts[1]) : r;
+    }, "") ?? ""
+  );
+}
+
+export function setCookie(name: string, value: string, days: number) {
+  const expires = new Date(Date.now() + days * 864e5).toUTCString();
+  if (globalThis?.window?.document) {
+    globalThis.window.document.cookie =
+      name + "=" + encodeURIComponent(value) + "; expires=" + expires + "; path=/";
+  }
+}
+
+export function deleteCookie(name: string) {
+  if (globalThis?.window?.document) {
+    globalThis.window.document.cookie = name + "=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/";
+  }
+}
+
+export function getServerSideCookie(req: Request, name: string): string {
+  const cookie = req.headers
+    .get("cookie")
+    ?.split(";")
+    .find((c) => c.trim().startsWith(name))
+    ?.split("=")[1];
+  return cookie ? decodeURIComponent(cookie) : "";
+}
+
+export function decodeCookie(cookieValue: string): any {
+  try {
+    return JSON.parse(decodeURIComponent(cookieValue));
+  } catch {
+    return null;
+  }
+}

package/src/sdk/createInvoke.ts

@@ -0,0 +1,57 @@
+/**
+ * Generic bridge that turns any async function into a TanStack Start server function.
+ *
+ * Used by @decocms/apps to expose commerce actions/loaders as typed
+ * `invoke.*` calls that execute on the server with full credentials.
+ *
+ * @example
+ * ```ts
+ * import { createInvokeFn } from "@decocms/start/sdk/createInvoke";
+ * import { addItemsToCart } from "./actions/checkout";
+ *
+ * export const invoke = {
+ *   vtex: {
+ *     actions: {
+ *       addItemsToCart: createInvokeFn(
+ *         (input: { orderFormId: string; orderItems: CartItem[] }) =>
+ *           addItemsToCart(input.orderFormId, input.orderItems),
+ *         { unwrap: true },
+ *       ),
+ *     },
+ *   },
+ * };
+ *
+ * // Client-side usage:
+ * await invoke.vtex.actions.addItemsToCart({ data: { orderFormId, orderItems } });
+ * ```
+ */
+import { createServerFn } from "@tanstack/react-start";
+
+export interface InvokeFnOpts {
+  /**
+   * When true, extracts `.data` from the result before returning.
+   * Use for VTEX checkout functions that return VtexFetchResult<T>
+   * (i.e. `{ data: T, setCookies: string[] }`).
+   */
+  unwrap?: boolean;
+}
+
+/**
+ * Transforms an async function into a `createServerFn` wrapper.
+ *
+ * - Client calls: `fn({ data: input })`
+ * - Server executes: `action(input)`
+ * - If `unwrap: true`, extracts `.data` from VtexFetchResult-shaped results
+ */
+export function createInvokeFn<TInput, TOutput>(
+  action: (input: TInput) => Promise<TOutput>,
+  opts?: InvokeFnOpts,
+): (ctx: { data: TInput }) => Promise<TOutput> {
+  return createServerFn({ method: "POST" }).handler(async (ctx) => {
+    const result = await action(ctx.data as TInput);
+    if (opts?.unwrap && result && typeof result === "object" && "data" in result) {
+      return (result as any).data;
+    }
+    return result;
+  }) as unknown as (ctx: { data: TInput }) => Promise<TOutput>;
+}

package/src/sdk/csp.ts

@@ -0,0 +1,59 @@
+/**
+ * Content Security Policy header utilities.
+ *
+ * Sets frame-ancestors to allow the Deco admin to embed the
+ * storefront in an iframe for live preview.
+ */
+
+const DEFAULT_ADMIN_ORIGINS = ["https://admin.deco.cx", "https://deco.cx", "https://localhost:*"];
+
+export interface CSPOptions {
+  /** Additional origins allowed to frame the storefront. */
+  extraOrigins?: string[];
+  /**
+   * Deco admin origins. Defaults to admin.deco.cx + localhost.
+   * Set to empty array to disallow all external framing.
+   */
+  adminOrigins?: string[];
+}
+
+/**
+ * Set Content-Security-Policy frame-ancestors header on a Response.
+ *
+ * This is required for the Deco admin live preview iframe to work.
+ * Also removes X-Frame-Options if present (CSP supersedes it).
+ *
+ * @example
+ * ```ts
+ * import { setCSPHeaders } from "@decocms/start/sdk/csp";
+ *
+ * // In middleware:
+ * const response = await next();
+ * setCSPHeaders(response);
+ * return response;
+ * ```
+ */
+export function setCSPHeaders(response: Response, options?: CSPOptions): void {
+  const origins = [
+    "'self'",
+    ...(options?.adminOrigins ?? DEFAULT_ADMIN_ORIGINS),
+    ...(options?.extraOrigins ?? []),
+  ];
+
+  response.headers.set("Content-Security-Policy", `frame-ancestors ${origins.join(" ")}`);
+
+  response.headers.delete("X-Frame-Options");
+}
+
+/**
+ * Build the CSP header value string without applying it.
+ * Useful when constructing headers in route definitions.
+ */
+export function buildCSPHeaderValue(options?: CSPOptions): string {
+  const origins = [
+    "'self'",
+    ...(options?.adminOrigins ?? DEFAULT_ADMIN_ORIGINS),
+    ...(options?.extraOrigins ?? []),
+  ];
+  return `frame-ancestors ${origins.join(" ")}`;
+}