@decocms/start 0.19.0

package/src/sdk/env.ts

@@ -0,0 +1,27 @@
+/**
+ * Centralized environment detection for @decocms/start.
+ *
+ * Works in Cloudflare Workers (wrangler dev), Node, and Vite SSR.
+ * Evaluates lazily on first call so it picks up env vars set after module load.
+ */
+
+let _isDev: boolean | null = null;
+
+/**
+ * Returns `true` when running in a development environment.
+ *
+ * Detection order:
+ *  1. `DECO_CACHE_DISABLE=true` — explicit opt-in (always wins)
+ *  2. `NODE_ENV=development`    — standard Node/Vite convention
+ *
+ * The result is memoised after the first evaluation.
+ */
+export function isDevMode(): boolean {
+  if (_isDev !== null) return _isDev;
+
+  const env = typeof globalThis.process !== "undefined" ? globalThis.process.env : undefined;
+
+  _isDev = env?.DECO_CACHE_DISABLE === "true" || env?.NODE_ENV === "development";
+
+  return _isDev;
+}

package/src/sdk/index.ts

@@ -0,0 +1,63 @@
+export { ANALYTICS_SCRIPT, type DataEventParams, gtmScript, useSendEvent } from "./analytics";
+export {
+  type CachedLoaderOptions,
+  type CachePolicy,
+  clearLoaderCache,
+  createCachedLoader,
+  getLoaderCacheStats,
+} from "./cachedLoader";
+export {
+  type CacheHeadersConfig,
+  type CacheProfile,
+  cacheHeaders,
+  detectCacheProfile,
+  getCacheProfileConfig,
+  registerCachePattern,
+  routeCacheDefaults,
+} from "./cacheHeaders";
+export { clx } from "./clx";
+export { decodeCookie, deleteCookie, getCookie, getServerSideCookie, setCookie } from "./cookie";
+export { buildCSPHeaderValue, type CSPOptions, setCSPHeaders } from "./csp";
+export { isDevMode } from "./env";
+export {
+  createInstrumentedFetch,
+  type FetchInstrumentationOptions,
+  type FetchMetrics,
+  instrumentFetch,
+} from "./instrumentedFetch";
+export { batchInvoke, createInvokeProxy, type InvokeProxy, invokeQueryOptions } from "./invoke";
+export { createCacheControlCollector, mergeCacheControl } from "./mergeCacheControl";
+export {
+  addRedirects,
+  loadRedirects,
+  matchRedirect,
+  parseRedirectsCsv,
+  type Redirect,
+  type RedirectMap,
+} from "./redirects";
+export { RequestContext, type RequestContextData } from "./requestContext";
+export { createServerTimings, type ServerTimings } from "./serverTimings";
+export { type ReactiveSignal, signal } from "./signal";
+export {
+  canonicalUrl,
+  cleanPathForCacheKey,
+  hasTrackingParams,
+  stripTrackingParams,
+} from "./urlUtils";
+export {
+  checkDesktop,
+  checkMobile,
+  checkTablet,
+  type Device,
+  detectDevice,
+  useDevice,
+} from "./useDevice";
+export { useId } from "./useId";
+export { usePartialSection, useScript, useScriptAsDataURI, useSection } from "./useScript";
+export { createDecoWorkerEntry, type DecoWorkerEntryOptions } from "./workerEntry";
+export {
+  isWrappedError,
+  unwrapError,
+  type WrappedError,
+  wrapCaughtErrors,
+} from "./wrapCaughtErrors";

package/src/sdk/instrumentedFetch.ts

@@ -0,0 +1,137 @@
+/**
+ * Instrumented fetch wrapper that adds logging and tracing to outbound HTTP calls.
+ *
+ * Designed to be wired into commerce clients (VTEX, Shopify) so all
+ * API calls become visible in dev logs and production traces.
+ *
+ * @example
+ * ```ts
+ * import { createInstrumentedFetch } from "@decocms/start/sdk/instrumentedFetch";
+ *
+ * const vtexFetch = createInstrumentedFetch("vtex");
+ *
+ * // Use it instead of global fetch:
+ * const response = await vtexFetch("https://account.vtexcommercestable.com.br/api/...");
+ * ```
+ */
+
+import { getTracer } from "../middleware/observability";
+
+export interface FetchInstrumentationOptions {
+  /** Tag for log/trace grouping (e.g., "vtex", "shopify"). */
+  name: string;
+  /** Enable request/response logging. Default: true in development. */
+  logging?: boolean;
+  /** Enable tracing via the configured TracerAdapter. Default: true. */
+  tracing?: boolean;
+  /** Callback when a request completes (for custom metrics). */
+  onComplete?: (info: FetchMetrics) => void;
+  /**
+   * Underlying fetch implementation to wrap. Defaults to `globalThis.fetch`.
+   * Use this when the client already has a custom fetch (e.g. with cookies,
+   * custom headers, or a proxy) that must be preserved.
+   */
+  baseFetch?: typeof fetch;
+}
+
+export interface FetchMetrics {
+  name: string;
+  url: string;
+  method: string;
+  status: number;
+  durationMs: number;
+  cached: boolean;
+}
+
+const isDev =
+  typeof globalThis.process !== "undefined" && globalThis.process.env?.NODE_ENV === "development";
+
+/**
+ * Creates a fetch wrapper that instruments all requests for a given integration.
+ */
+export function createInstrumentedFetch(
+  nameOrOptions: string | FetchInstrumentationOptions,
+): typeof fetch {
+  const options: FetchInstrumentationOptions =
+    typeof nameOrOptions === "string" ? { name: nameOrOptions } : nameOrOptions;
+
+  const {
+    name,
+    logging = isDev,
+    tracing = true,
+    onComplete,
+    baseFetch = globalThis.fetch,
+  } = options;
+
+  return async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    const url =
+      typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+    const method = init?.method || "GET";
+    const startTime = performance.now();
+
+    const doFetch = async (): Promise<Response> => {
+      if (logging) {
+        console.log(`[${name}] ${method} ${truncateUrl(url)}`);
+      }
+
+      const response = await baseFetch(input, init);
+      const durationMs = performance.now() - startTime;
+      const cached = response.headers.get("x-cache") === "HIT";
+
+      if (logging) {
+        const color = response.ok ? "\x1b[32m" : "\x1b[31m";
+        console.log(
+          `[${name}] ${color}${response.status}\x1b[0m ${method} ${truncateUrl(url)} ${durationMs.toFixed(0)}ms${cached ? " (cached)" : ""}`,
+        );
+      }
+
+      onComplete?.({
+        name,
+        url,
+        method,
+        status: response.status,
+        durationMs,
+        cached,
+      });
+
+      return response;
+    };
+
+    if (tracing) {
+      const tracer = getTracer();
+      if (tracer) {
+        const span = tracer.startSpan(`${name}.fetch`, {
+          "http.method": method,
+          "http.url": url,
+          "fetch.integration": name,
+        });
+
+        try {
+          const response = await doFetch();
+          span.end();
+          return response;
+        } catch (error) {
+          span.setError?.(error);
+          span.end();
+          throw error;
+        }
+      }
+    }
+
+    return doFetch();
+  };
+}
+
+function truncateUrl(url: string, maxLen = 120): string {
+  if (url.length <= maxLen) return url;
+  return url.slice(0, maxLen - 3) + "...";
+}
+
+/**
+ * Wraps an existing fetch function with logging and tracing instrumentation.
+ * Unlike `createInstrumentedFetch`, this preserves the original fetch's
+ * behavior (custom headers, cookies, proxy logic) and adds observability on top.
+ */
+export function instrumentFetch(originalFetch: typeof fetch, name: string): typeof fetch {
+  return createInstrumentedFetch({ name, baseFetch: originalFetch });
+}

package/src/sdk/invoke.ts

@@ -0,0 +1,133 @@
+/**
+ * Typed invoke proxy for client-side RPC to deco loaders/actions.
+ *
+ * Creates a Proxy object that maps loader keys to `POST /deco/invoke/:key` calls,
+ * providing a type-safe, ergonomic API for client-side data fetching.
+ *
+ * @example
+ * ```ts
+ * // Define your loader registry type
+ * type Loaders = {
+ *   "vtex/loaders/intelligentSearch/productList.ts": (props: { query: string }) => Promise<Product[]>;
+ *   "vtex/loaders/intelligentSearch/productDetailsPage.ts": (props: { slug: string }) => Promise<ProductDetailsPage>;
+ * };
+ *
+ * const invoke = createInvokeProxy<Loaders>("/deco/invoke");
+ *
+ * // Type-safe calls:
+ * const products = await invoke["vtex/loaders/intelligentSearch/productList.ts"]({ query: "shoes" });
+ * ```
+ */
+
+export type InvokeProxy<TLoaders extends Record<string, (props: any) => Promise<any>>> = {
+  [K in keyof TLoaders]: TLoaders[K] extends (props: infer P) => Promise<infer R>
+    ? (props: P) => Promise<R>
+    : never;
+};
+
+/**
+ * Creates a proxy that turns loader key access into fetch calls to `/deco/invoke/:key`.
+ */
+export function createInvokeProxy<TLoaders extends Record<string, (props: any) => Promise<any>>>(
+  basePath = "/deco/invoke",
+): InvokeProxy<TLoaders> {
+  return new Proxy({} as InvokeProxy<TLoaders>, {
+    get(_target, prop: string) {
+      return async (props: unknown) => {
+        const url = `${basePath}/${encodeURIComponent(prop)}`;
+        const response = await fetch(url, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(props ?? {}),
+        });
+
+        if (!response.ok) {
+          const error = await response.json().catch(() => ({ error: response.statusText }));
+          throw new Error(
+            `Invoke ${prop} failed (${response.status}): ${(error as any).error || response.statusText}`,
+          );
+        }
+
+        return response.json();
+      };
+    },
+  });
+}
+
+/**
+ * Batch invoke multiple loaders in a single request.
+ *
+ * @example
+ * ```ts
+ * const results = await batchInvoke("/deco/invoke", {
+ *   products: { __resolveType: "vtex/loaders/productList.ts", query: "shoes" },
+ *   details: { __resolveType: "vtex/loaders/productDetailsPage.ts", slug: "shoe-1" },
+ * });
+ * ```
+ */
+export async function batchInvoke<T extends Record<string, unknown>>(
+  basePath: string,
+  payloads: T,
+): Promise<{ [K in keyof T]: unknown }> {
+  const response = await fetch(basePath, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payloads),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Batch invoke failed (${response.status})`);
+  }
+
+  return response.json();
+}
+
+/**
+ * Helper to create TanStack Query `queryOptions` for an invoke call.
+ * The storefront must have `@tanstack/react-query` installed.
+ *
+ * @example
+ * ```ts
+ * import { useQuery } from "@tanstack/react-query";
+ * import { invokeQueryOptions } from "@decocms/start/sdk/invoke";
+ *
+ * const options = invokeQueryOptions(
+ *   "vtex/loaders/productList.ts",
+ *   { query: "shoes" },
+ *   { staleTime: 60_000 }
+ * );
+ *
+ * // In a component:
+ * const { data } = useQuery(options);
+ *
+ * // In a route loader:
+ * queryClient.ensureQueryData(options);
+ * ```
+ */
+export function invokeQueryOptions<TResult = unknown>(
+  key: string,
+  props: unknown,
+  options?: { staleTime?: number; gcTime?: number; basePath?: string },
+) {
+  const basePath = options?.basePath ?? "/deco/invoke";
+
+  return {
+    queryKey: ["deco-invoke", key, props] as const,
+    queryFn: async (): Promise<TResult> => {
+      const url = `${basePath}/${encodeURIComponent(key)}`;
+      const response = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(props ?? {}),
+      });
+
+      if (!response.ok) {
+        throw new Error(`Invoke ${key} failed (${response.status})`);
+      }
+
+      return response.json();
+    },
+    staleTime: options?.staleTime,
+    gcTime: options?.gcTime,
+  };
+}

package/src/sdk/mergeCacheControl.ts

@@ -0,0 +1,150 @@
+/**
+ * Cache-Control merge utility.
+ *
+ * When a page makes multiple backend calls with different cache lifetimes,
+ * the final page response must use the most restrictive (shortest) cache
+ * values. This utility merges multiple Cache-Control headers following
+ * the "most restrictive wins" strategy.
+ *
+ * @example
+ * ```ts
+ * import { mergeCacheControl } from "@decocms/start/sdk/mergeCacheControl";
+ *
+ * // Product loader returns 60s, mega menu returns 3600s
+ * const merged = mergeCacheControl([
+ *   "public, s-maxage=60, stale-while-revalidate=300",
+ *   "public, s-maxage=3600, stale-while-revalidate=86400",
+ * ]);
+ * // => "public, s-maxage=60, stale-while-revalidate=300"
+ * ```
+ */
+
+interface ParsedCacheControl {
+  isPublic: boolean;
+  isPrivate: boolean;
+  noCache: boolean;
+  noStore: boolean;
+  maxAge?: number;
+  sMaxAge?: number;
+  staleWhileRevalidate?: number;
+  staleIfError?: number;
+  mustRevalidate: boolean;
+}
+
+function safeParseInt(value: string | undefined): number | undefined {
+  if (!value) return undefined;
+  const n = parseInt(value, 10);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+function parse(header: string): ParsedCacheControl {
+  const directives = header.split(",").map((d) => d.trim().toLowerCase());
+
+  const result: ParsedCacheControl = {
+    isPublic: false,
+    isPrivate: false,
+    noCache: false,
+    noStore: false,
+    mustRevalidate: false,
+  };
+
+  for (const directive of directives) {
+    if (directive === "public") result.isPublic = true;
+    else if (directive === "private") result.isPrivate = true;
+    else if (directive === "no-cache") result.noCache = true;
+    else if (directive === "no-store") result.noStore = true;
+    else if (directive === "must-revalidate") result.mustRevalidate = true;
+    else if (directive.startsWith("max-age=")) {
+      result.maxAge = safeParseInt(directive.split("=")[1]);
+    } else if (directive.startsWith("s-maxage=")) {
+      result.sMaxAge = safeParseInt(directive.split("=")[1]);
+    } else if (directive.startsWith("stale-while-revalidate=")) {
+      result.staleWhileRevalidate = safeParseInt(directive.split("=")[1]);
+    } else if (directive.startsWith("stale-if-error=")) {
+      result.staleIfError = safeParseInt(directive.split("=")[1]);
+    }
+  }
+
+  return result;
+}
+
+function minDefined(...values: (number | undefined)[]): number | undefined {
+  const defined = values.filter((v): v is number => v != null);
+  return defined.length > 0 ? Math.min(...defined) : undefined;
+}
+
+/**
+ * Merge multiple Cache-Control headers using "most restrictive wins".
+ *
+ * - If any header is `private`, the result is `private`
+ * - If any header has `no-store`, the result has `no-store`
+ * - Numeric values (max-age, s-maxage, swr) use the minimum
+ */
+export function mergeCacheControl(headers: string[]): string {
+  if (headers.length === 0) return "public, s-maxage=0";
+  if (headers.length === 1) return headers[0];
+
+  const parsed = headers.map(parse);
+
+  const anyPrivate = parsed.some((p) => p.isPrivate);
+  const anyNoStore = parsed.some((p) => p.noStore);
+  const anyNoCache = parsed.some((p) => p.noCache);
+  const anyMustRevalidate = parsed.some((p) => p.mustRevalidate);
+
+  if (anyNoStore) {
+    return "private, no-cache, no-store, must-revalidate";
+  }
+
+  if (anyPrivate) {
+    const maxAge = minDefined(...parsed.map((p) => p.maxAge));
+    const parts = ["private"];
+    if (anyNoCache) parts.push("no-cache");
+    if (maxAge != null) parts.push(`max-age=${maxAge}`);
+    if (anyMustRevalidate) parts.push("must-revalidate");
+    return parts.join(", ");
+  }
+
+  const maxAge = minDefined(...parsed.map((p) => p.maxAge));
+  const sMaxAge = minDefined(...parsed.map((p) => p.sMaxAge));
+  const swr = minDefined(...parsed.map((p) => p.staleWhileRevalidate));
+  const sie = minDefined(...parsed.map((p) => p.staleIfError));
+
+  const parts: string[] = ["public"];
+  if (maxAge != null) parts.push(`max-age=${maxAge}`);
+  if (sMaxAge != null) parts.push(`s-maxage=${sMaxAge}`);
+  if (swr != null) parts.push(`stale-while-revalidate=${swr}`);
+  if (sie != null) parts.push(`stale-if-error=${sie}`);
+  if (anyMustRevalidate) parts.push("must-revalidate");
+
+  return parts.join(", ");
+}
+
+/**
+ * Accumulator for collecting cache control headers across loaders.
+ *
+ * Use in middleware to collect headers from each loader call and
+ * compute the final merged header at the end.
+ *
+ * @example
+ * ```ts
+ * const collector = createCacheControlCollector();
+ * collector.add("public, s-maxage=60");
+ * collector.add("public, s-maxage=3600");
+ * response.headers.set("Cache-Control", collector.result());
+ * // => "public, s-maxage=60"
+ * ```
+ */
+export function createCacheControlCollector() {
+  const headers: string[] = [];
+  return {
+    add(header: string) {
+      headers.push(header);
+    },
+    result(): string {
+      return mergeCacheControl(headers);
+    },
+    get count() {
+      return headers.length;
+    },
+  };
+}