@decocms/start 0.19.0

package/src/sdk/redirects.ts

@@ -0,0 +1,217 @@
+/**
+ * CMS-managed redirect system.
+ *
+ * Loads redirect definitions from .deco/blocks/ and provides
+ * fast path matching for use in TanStack Start middleware.
+ *
+ * Supports:
+ * - Exact path matches (/old-page -> /new-page)
+ * - Glob patterns (/old/* -> /new/*)
+ * - Permanent (301) and temporary (302) redirects
+ * - CSV import for bulk redirects
+ *
+ * @example
+ * ```ts
+ * // In TanStack Start middleware
+ * import { loadRedirects, matchRedirect } from "@decocms/start/sdk/redirects";
+ * import { loadBlocks } from "@decocms/start/cms";
+ *
+ * const redirects = loadRedirects(loadBlocks());
+ *
+ * const middleware = createMiddleware().server(async ({ next, request }) => {
+ *   const url = new URL(request.url);
+ *   const redirect = matchRedirect(url.pathname, redirects);
+ *   if (redirect) {
+ *     return new Response(null, {
+ *       status: redirect.status,
+ *       headers: { Location: redirect.to },
+ *     });
+ *   }
+ *   return next();
+ * });
+ * ```
+ */
+
+// -------------------------------------------------------------------------
+// Types
+// -------------------------------------------------------------------------
+
+export interface Redirect {
+  from: string;
+  to: string;
+  status: 301 | 302;
+}
+
+export interface RedirectMap {
+  /** Exact match redirects for O(1) lookup. */
+  exact: Map<string, Redirect>;
+  /** Glob/prefix redirects checked sequentially (few in practice). */
+  patterns: Array<{ prefix: string; redirect: Redirect }>;
+}
+
+// -------------------------------------------------------------------------
+// Loading from CMS blocks
+// -------------------------------------------------------------------------
+
+interface BlockRedirectEntry {
+  from: string;
+  to: string;
+  type?: "permanent" | "temporary";
+}
+
+const REDIRECT_RESOLVE_TYPES = new Set([
+  "website/loaders/redirect.ts",
+  "website/loaders/redirects.ts",
+  "website/loaders/redirectsFromCsv.ts",
+  "deco-sites/std/loaders/x/redirects.ts",
+]);
+
+/**
+ * Load all redirect definitions from CMS blocks.
+ *
+ * Scans the blocks for known redirect resolve types and builds
+ * a fast-lookup redirect map.
+ */
+export function loadRedirects(blocks: Record<string, unknown>): RedirectMap {
+  const exact = new Map<string, Redirect>();
+  const patterns: Array<{ prefix: string; redirect: Redirect }> = [];
+
+  for (const [_key, block] of Object.entries(blocks)) {
+    if (!block || typeof block !== "object") continue;
+    const obj = block as Record<string, unknown>;
+    const resolveType = obj.__resolveType as string | undefined;
+
+    if (!resolveType || !REDIRECT_RESOLVE_TYPES.has(resolveType)) continue;
+
+    const entries = (obj.redirects ?? obj.redirect) as
+      | BlockRedirectEntry[]
+      | BlockRedirectEntry
+      | undefined;
+
+    if (!entries) continue;
+
+    const list = Array.isArray(entries) ? entries : [entries];
+
+    for (const entry of list) {
+      if (!entry.from || !entry.to) continue;
+
+      const redirect: Redirect = {
+        from: normalizePath(entry.from),
+        to: entry.to,
+        status: entry.type === "permanent" ? 301 : 302,
+      };
+
+      if (redirect.from.includes("*")) {
+        const prefix = redirect.from.replace(/\*+$/, "");
+        patterns.push({ prefix, redirect });
+      } else {
+        exact.set(redirect.from, redirect);
+      }
+    }
+  }
+
+  return { exact, patterns };
+}
+
+// -------------------------------------------------------------------------
+// CSV import
+// -------------------------------------------------------------------------
+
+/**
+ * Parse a CSV string into redirect entries.
+ *
+ * Expected format: `from,to[,type]` (one per line).
+ * Lines starting with # are comments. Empty lines are skipped.
+ * Type is "permanent" (301) or "temporary" (302, default).
+ */
+export function parseRedirectsCsv(csv: string): Redirect[] {
+  const redirects: Redirect[] = [];
+  const lines = csv.split("\n");
+
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+
+    const parts = line.split(",").map((p) => p.trim());
+    if (parts.length < 2) continue;
+
+    const [from, to, type] = parts;
+    if (!from || !to) continue;
+
+    redirects.push({
+      from: normalizePath(from),
+      to,
+      status: type === "permanent" || type === "301" ? 301 : 302,
+    });
+  }
+
+  return redirects;
+}
+
+/**
+ * Add parsed redirects to an existing redirect map.
+ */
+export function addRedirects(map: RedirectMap, redirects: Redirect[]): void {
+  for (const redirect of redirects) {
+    if (redirect.from.includes("*")) {
+      const prefix = redirect.from.replace(/\*+$/, "");
+      map.patterns.push({ prefix, redirect });
+    } else {
+      map.exact.set(redirect.from, redirect);
+    }
+  }
+}
+
+// -------------------------------------------------------------------------
+// Matching
+// -------------------------------------------------------------------------
+
+/**
+ * Find a redirect matching the given path.
+ *
+ * Checks exact matches first (O(1)), then glob patterns (O(n), but
+ * typically few patterns exist).
+ */
+export function matchRedirect(pathname: string, map: RedirectMap): Redirect | null {
+  const normalized = normalizePath(pathname);
+
+  const exactMatch = map.exact.get(normalized);
+  if (exactMatch) return exactMatch;
+
+  for (const { prefix, redirect } of map.patterns) {
+    if (normalized.startsWith(prefix)) {
+      const suffix = normalized.slice(prefix.length);
+      const to = redirect.to.includes("*") ? redirect.to.replace("*", suffix) : redirect.to;
+      return { ...redirect, to };
+    }
+  }
+
+  return null;
+}
+
+// -------------------------------------------------------------------------
+// Helpers
+// -------------------------------------------------------------------------
+
+function normalizePath(path: string): string {
+  let p = path.trim();
+
+  // If the "from" is a full URL, extract just the pathname
+  if (p.startsWith("http://") || p.startsWith("https://")) {
+    try {
+      p = new URL(p).pathname;
+    } catch {
+      // malformed URL, keep as-is and try the prefix fallback
+      const slashIdx = p.indexOf("/", p.indexOf("//") + 2);
+      p = slashIdx >= 0 ? p.slice(slashIdx) : p;
+    }
+  }
+
+  if (!p.startsWith("/")) {
+    p = "/" + p;
+  }
+  if (p.length > 1 && p.endsWith("/")) {
+    p = p.slice(0, -1);
+  }
+  return p.toLowerCase();
+}

package/src/sdk/requestContext.ts

@@ -0,0 +1,184 @@
+/**
+ * Per-request context via AsyncLocalStorage.
+ *
+ * Binds request-scoped state (request, abort signal, device info, flags)
+ * that any code in the call stack can access without prop drilling.
+ *
+ * Requires `nodejs_compat` in wrangler.jsonc (already enabled).
+ *
+ * **Design decisions:**
+ * - We do NOT monkey-patch global `fetch`. Instead, `RequestContext.fetch`
+ *   provides a fetch that auto-injects the request's AbortSignal.
+ * - The context is optional -- code that doesn't need it just doesn't call it.
+ *   Commerce loaders receive it explicitly via the updated `CommerceLoader` sig.
+ *
+ * @example
+ * ```ts
+ * // In TanStack Start middleware:
+ * import { RequestContext } from "@decocms/start/sdk/requestContext";
+ *
+ * const middleware = createMiddleware().server(async ({ next, request }) => {
+ *   return RequestContext.run(request, () => next());
+ * });
+ *
+ * // Anywhere in the call stack:
+ * const req = RequestContext.request;       // the current request
+ * const signal = RequestContext.signal;     // AbortSignal
+ * const resp = await RequestContext.fetch(url); // auto-aborts on disconnect
+ * ```
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+// -------------------------------------------------------------------------
+// Types
+// -------------------------------------------------------------------------
+
+export interface RequestContextData {
+  request: Request;
+  signal: AbortSignal;
+  startedAt: number;
+  /** Lazily computed device type. */
+  _device?: "mobile" | "desktop";
+  /** Lazily computed bot detection result. */
+  _isBot?: boolean;
+  /** Arbitrary bag for middleware to attach custom data. */
+  bag: Map<string, unknown>;
+}
+
+// -------------------------------------------------------------------------
+// Storage
+// -------------------------------------------------------------------------
+
+const storage = new AsyncLocalStorage<RequestContextData>();
+
+const MOBILE_RE = /mobile|android|iphone|ipad|ipod|webos|blackberry|opera mini|iemobile/i;
+const BOT_RE =
+  /bot|crawl|spider|slurp|bingpreview|facebookexternalhit|linkedinbot|twitterbot|whatsapp|telegram|googlebot|yandex|baidu|duckduck/i;
+
+// -------------------------------------------------------------------------
+// Public API
+// -------------------------------------------------------------------------
+
+export const RequestContext = {
+  /**
+   * Run a function within a request context.
+   *
+   * Call this at the outermost middleware level. Everything inside
+   * the callback (loaders, resolvers, utilities) can access the
+   * context via the static getters.
+   */
+  run<T>(request: Request, fn: () => T): T {
+    const controller = new AbortController();
+
+    if (request.signal) {
+      if (request.signal.aborted) {
+        controller.abort(request.signal.reason);
+      } else {
+        request.signal.addEventListener("abort", () => controller.abort(request.signal.reason), {
+          once: true,
+        });
+      }
+    }
+
+    const ctx: RequestContextData = {
+      request,
+      signal: controller.signal,
+      startedAt: Date.now(),
+      bag: new Map(),
+    };
+
+    return storage.run(ctx, fn);
+  },
+
+  /**
+   * Get the current request context, or null if not in a request scope.
+   */
+  get current(): RequestContextData | null {
+    return storage.getStore() ?? null;
+  },
+
+  /**
+   * Get the current Request object.
+   * @throws if called outside a request context
+   */
+  get request(): Request {
+    const ctx = storage.getStore();
+    if (!ctx) throw new Error("RequestContext.request accessed outside a request scope");
+    return ctx.request;
+  },
+
+  /**
+   * Get the current AbortSignal.
+   * Use this to cancel in-flight operations when the client disconnects.
+   */
+  get signal(): AbortSignal {
+    const ctx = storage.getStore();
+    if (!ctx) throw new Error("RequestContext.signal accessed outside a request scope");
+    return ctx.signal;
+  },
+
+  /**
+   * Detected device type based on User-Agent.
+   */
+  get device(): "mobile" | "desktop" {
+    const ctx = storage.getStore();
+    if (!ctx) return "desktop";
+    if (ctx._device) return ctx._device;
+    const ua = ctx.request.headers.get("user-agent") ?? "";
+    ctx._device = MOBILE_RE.test(ua) ? "mobile" : "desktop";
+    return ctx._device;
+  },
+
+  /**
+   * Whether the request appears to be from a bot/crawler.
+   */
+  get isBot(): boolean {
+    const ctx = storage.getStore();
+    if (!ctx) return false;
+    if (ctx._isBot !== undefined) return ctx._isBot;
+    const ua = ctx.request.headers.get("user-agent") ?? "";
+    ctx._isBot = BOT_RE.test(ua);
+    return ctx._isBot;
+  },
+
+  /**
+   * Elapsed time since the request started (in milliseconds).
+   */
+  get elapsed(): number {
+    const ctx = storage.getStore();
+    if (!ctx) return 0;
+    return Date.now() - ctx.startedAt;
+  },
+
+  /**
+   * Fetch with automatic AbortSignal injection.
+   *
+   * When the client disconnects, this fetch aborts automatically.
+   * This is NOT a global monkey-patch -- only code that explicitly
+   * calls `RequestContext.fetch()` gets this behavior.
+   */
+  fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response> {
+    const ctx = storage.getStore();
+    if (!ctx) return globalThis.fetch(input, init);
+
+    return globalThis.fetch(input, {
+      ...init,
+      signal: init?.signal ?? ctx.signal,
+    });
+  },
+
+  /**
+   * Get/set arbitrary values in the request bag.
+   * Useful for middleware to pass data to loaders.
+   */
+  getBag<T>(key: string): T | undefined {
+    const ctx = storage.getStore();
+    return ctx?.bag.get(key) as T | undefined;
+  },
+
+  setBag(key: string, value: unknown): void {
+    const ctx = storage.getStore();
+    ctx?.bag.set(key, value);
+  },
+};

package/src/sdk/serverTimings.ts

@@ -0,0 +1,68 @@
+/**
+ * Server-Timing header builder.
+ *
+ * Tracks named timing entries during a request and serializes them
+ * into the `Server-Timing` HTTP header for visibility in DevTools.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Server-Timing
+ *
+ * @example
+ * ```ts
+ * const timings = createServerTimings();
+ * const end = timings.start("resolve-cms");
+ * await resolvePage();
+ * end();
+ * response.headers.set("Server-Timing", timings.toHeader());
+ * ```
+ */
+export interface ServerTimings {
+  /** Start a named timing. Returns a function to call when done. */
+  start(name: string, description?: string): () => void;
+  /** Record a completed timing with a known duration. */
+  record(name: string, durationMs: number, description?: string): void;
+  /** Serialize all timings to a `Server-Timing` header value. */
+  toHeader(): string;
+  /** Get all recorded entries for diagnostics. */
+  entries(): TimingEntry[];
+}
+
+export interface TimingEntry {
+  name: string;
+  durationMs: number;
+  description?: string;
+}
+
+export function createServerTimings(): ServerTimings {
+  const timingEntries: TimingEntry[] = [];
+
+  return {
+    start(name: string, description?: string) {
+      const startTime = performance.now();
+      return () => {
+        const durationMs = performance.now() - startTime;
+        timingEntries.push({ name, durationMs, description });
+      };
+    },
+
+    record(name: string, durationMs: number, description?: string) {
+      timingEntries.push({ name, durationMs, description });
+    },
+
+    toHeader(): string {
+      return timingEntries
+        .map((entry) => {
+          let value = entry.name;
+          if (entry.description) {
+            value += `;desc="${entry.description}"`;
+          }
+          value += `;dur=${entry.durationMs.toFixed(1)}`;
+          return value;
+        })
+        .join(", ");
+    },
+
+    entries() {
+      return [...timingEntries];
+    },
+  };
+}

package/src/sdk/signal.ts

@@ -0,0 +1,41 @@
+/**
+ * Reactive signal backed by @tanstack/store.
+ *
+ * Drop-in replacement for the preact signals shim.
+ * Preserves the .value getter/setter API so consumers don't need to change.
+ *
+ * For React components that need to re-render on state changes,
+ * use the useStore() hook from @tanstack/react-store:
+ *
+ *   import { useStore } from "@tanstack/react-store";
+ *   const value = useStore(mySignal.store);
+ */
+import { Store } from "@tanstack/store";
+
+export interface ReactiveSignal<T> {
+  readonly store: Store<T>;
+  value: T;
+  peek(): T;
+  subscribe(fn: () => void): () => void;
+}
+
+export function signal<T>(initialValue: T): ReactiveSignal<T> {
+  const store = new Store<T>(initialValue);
+
+  return {
+    store,
+    get value(): T {
+      return store.state;
+    },
+    set value(v: T) {
+      store.setState(() => v);
+    },
+    peek(): T {
+      return store.state;
+    },
+    subscribe(fn: () => void): () => void {
+      const sub = store.subscribe(() => fn());
+      return () => sub.unsubscribe();
+    },
+  };
+}

package/src/sdk/sitemap.ts

@@ -0,0 +1,143 @@
+/**
+ * Sitemap generation utilities.
+ *
+ * Provides XML sitemap generation from CMS page blocks and arbitrary
+ * URL lists. Designed to be composed with commerce-specific sitemap
+ * sources (VTEX, Shopify) in a TanStack Start API route.
+ *
+ * @example
+ * ```ts
+ * // src/routes/sitemap[.]xml.ts
+ * import { createAPIFileRoute } from "@tanstack/react-start/api";
+ * import { getCMSSitemapEntries, generateSitemapXml } from "@decocms/start/sdk/sitemap";
+ * import { getVtexSitemapEntries } from "@decocms/apps/vtex/utils/sitemap";
+ *
+ * export const APIRoute = createAPIFileRoute("/sitemap.xml")({
+ *   GET: async ({ request }) => {
+ *     const origin = new URL(request.url).origin;
+ *     const cmsEntries = getCMSSitemapEntries(origin);
+ *     const vtexEntries = await getVtexSitemapEntries(origin);
+ *     const xml = generateSitemapXml([...cmsEntries, ...vtexEntries]);
+ *     return new Response(xml, {
+ *       headers: {
+ *         "Content-Type": "application/xml",
+ *         "Cache-Control": "public, s-maxage=3600, stale-while-revalidate=86400",
+ *       },
+ *     });
+ *   },
+ * });
+ * ```
+ */
+
+import { getAllPages, loadBlocks } from "../cms/loader";
+
+// -------------------------------------------------------------------------
+// Types
+// -------------------------------------------------------------------------
+
+export interface SitemapEntry {
+  loc: string;
+  lastmod?: string;
+  changefreq?: "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";
+  priority?: number;
+}
+
+export interface SitemapOptions {
+  /** Maximum entries per sitemap (Google limit is 50,000). @default 50000 */
+  maxEntries?: number;
+}
+
+// -------------------------------------------------------------------------
+// CMS page entries
+// -------------------------------------------------------------------------
+
+/**
+ * Extract sitemap entries from CMS page blocks.
+ *
+ * Reads all pages from the block store and generates URLs from their
+ * path patterns (excluding wildcard-only patterns like `/*`).
+ */
+export function getCMSSitemapEntries(origin: string): SitemapEntry[] {
+  const pages = getAllPages();
+  const entries: SitemapEntry[] = [];
+  const today = new Date().toISOString().split("T")[0];
+
+  for (const { page } of pages) {
+    if (!page.path) continue;
+
+    if (page.path.includes("*") || page.path.includes(":")) continue;
+
+    const loc = `${origin}${page.path === "/" ? "" : page.path}`;
+    entries.push({
+      loc: loc || origin,
+      lastmod: today,
+      changefreq: page.path === "/" ? "daily" : "weekly",
+      priority: page.path === "/" ? 1.0 : 0.7,
+    });
+  }
+
+  return entries;
+}
+
+// -------------------------------------------------------------------------
+// XML generation
+// -------------------------------------------------------------------------
+
+function escapeXml(str: string): string {
+  return str
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
+}
+
+/**
+ * Generate a sitemap XML string from entries.
+ */
+export function generateSitemapXml(entries: SitemapEntry[], options?: SitemapOptions): string {
+  const max = options?.maxEntries ?? 50000;
+  const limited = entries.slice(0, max);
+
+  const urls = limited.map((entry) => {
+    let url = `  <url>\n    <loc>${escapeXml(entry.loc)}</loc>`;
+    if (entry.lastmod) url += `\n    <lastmod>${entry.lastmod}</lastmod>`;
+    if (entry.changefreq) url += `\n    <changefreq>${entry.changefreq}</changefreq>`;
+    if (entry.priority != null) url += `\n    <priority>${entry.priority.toFixed(1)}</priority>`;
+    url += "\n  </url>";
+    return url;
+  });
+
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+    ...urls,
+    "</urlset>",
+  ].join("\n");
+}
+
+/**
+ * Generate a sitemap index XML for splitting large sitemaps.
+ *
+ * @example
+ * ```ts
+ * const index = generateSitemapIndexXml([
+ *   `${origin}/sitemap-pages.xml`,
+ *   `${origin}/sitemap-products.xml`,
+ * ]);
+ * ```
+ */
+export function generateSitemapIndexXml(sitemapUrls: string[]): string {
+  const today = new Date().toISOString().split("T")[0];
+  const sitemaps = sitemapUrls.map(
+    (url) =>
+      `  <sitemap>\n    <loc>${escapeXml(url)}</loc>\n    <lastmod>${today}</lastmod>\n  </sitemap>`,
+  );
+
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+    ...sitemaps,
+    "</sitemapindex>",
+  ].join("\n");
+}