@decocms/blocks 7.0.0

package/src/sdk/redirects.ts

@@ -0,0 +1,225 @@
+/**
+ * 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",
+]);
+
+/**
+ * Register additional __resolveType strings that should be treated as redirect blocks.
+ * Useful for custom redirect loaders.
+ */
+export function registerRedirectResolveType(resolveType: string): void {
+  REDIRECT_RESOLVE_TYPES.add(resolveType);
+}
+
+/**
+ * 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,281 @@
+/**
+ * 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
+ * ```
+ */
+
+// The `node:async_hooks`-backed storage lives in a sibling module so that
+// bundlers targeting the browser can swap it for a no-op stub via the
+// `"browser"` export condition (see `./requestContextStorage` and the
+// `./sdk/requestContextStorage` entry in `package.json`). We import it through
+// the package's own name — NOT a relative path — because export conditions are
+// only consulted at package-specifier boundaries; a relative `./requestContextStorage`
+// would always resolve straight to the Node file and drag `node:async_hooks`
+// into the client graph, which is exactly the `UnhandledSchemeError` we're
+// avoiding. Node/Vitest resolve the `default`/`node` condition → real storage;
+// Next.js's client webpack compiler resolves `browser` → the stub.
+import { storage } from "@decocms/blocks/sdk/requestContextStorage";
+
+// -------------------------------------------------------------------------
+// Types
+// -------------------------------------------------------------------------
+
+export interface RequestContextData {
+  request: Request;
+  signal: AbortSignal;
+  startedAt: number;
+  /**
+   * Stable per-request identifier. Generated by `workerEntry.ts` from
+   * `cf-ray` when present, falling back to `crypto.randomUUID()`. Echoed
+   * back to the client as the `X-Request-Id` response header so:
+   *
+   *   - The producer Worker can stamp it on every log / span / metric
+   *     attribute (`request.id`) for join queries.
+   *   - The CF tail worker reads it from the response header and stamps
+   *     the same `request.id` on tail rows — restores the join key on a
+   *     channel that has no other shared identity with direct-POST.
+   *   - Clients can include it in support requests so we can pull the
+   *     full trace + logs from one ID.
+   *
+   * See `MIGRATION_TOOLING_PLAN.md` D-9 for the propagation policy.
+   */
+  requestId: string;
+  /** 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>;
+  /**
+   * Outgoing response headers that handlers can write to.
+   * Invoke handlers (actions/loaders) use this to forward Set-Cookie
+   * and other headers from upstream APIs (e.g., VTEX checkout).
+   * The invoke HTTP handler copies these into the final Response.
+   *
+   * This mirrors deco-cx/deco's `ctx.response.headers` pattern where
+   * `proxySetCookie(apiResponse.headers, ctx.response.headers)` forwards
+   * cookies transparently.
+   */
+  responseHeaders: Headers;
+}
+
+// -------------------------------------------------------------------------
+// Storage
+// -------------------------------------------------------------------------
+
+import { isMobileUA } from "./useDevice";
+
+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,
+        });
+      }
+    }
+
+    // Resolve request.id with explicit precedence so the choice is
+    // auditable from a single read:
+    //  (1) inbound `x-request-id` — caller-supplied (e.g. a load balancer
+    //      already tagged the request, or a synthetic test passed one in)
+    //  (2) `cf-ray` — Cloudflare's own per-request identifier, present
+    //      on every real Workers request and globally unique
+    //  (3) `crypto.randomUUID()` — last resort for tests and locally-run
+    //      dev without `cf-ray`
+    const incomingReqId = request.headers.get("x-request-id");
+    const cfRay = request.headers.get("cf-ray");
+    const requestId =
+      incomingReqId && incomingReqId.length > 0
+        ? incomingReqId
+        : cfRay && cfRay.length > 0
+          ? cfRay
+          : (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
+              ? crypto.randomUUID()
+              : `${Date.now()}-${Math.random().toString(16).slice(2)}`);
+
+    const ctx: RequestContextData = {
+      request,
+      signal: controller.signal,
+      startedAt: Date.now(),
+      requestId,
+      bag: new Map(),
+      responseHeaders: new Headers(),
+    };
+
+    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;
+  },
+
+  /**
+   * The stable per-request identifier — see `RequestContextData.requestId`
+   * for the full propagation policy. Returns `null` when called outside a
+   * request scope (vs throwing, because observability helpers in the
+   * shutdown path of a Worker may pull it lazily).
+   */
+  get requestId(): string | null {
+    return storage.getStore()?.requestId ?? null;
+  },
+
+  /**
+   * 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 = isMobileUA(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,
+    });
+  },
+
+  /**
+   * Outgoing response headers. Handlers write here; the invoke endpoint
+   * copies them into the HTTP Response (mirroring ctx.response.headers
+   * from deco-cx/deco).
+   */
+  get responseHeaders(): Headers {
+    const ctx = storage.getStore();
+    if (!ctx) throw new Error("RequestContext.responseHeaders accessed outside a request scope");
+    return ctx.responseHeaders;
+  },
+
+  /**
+   * 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);
+  },
+
+  /**
+   * Get an app's state from the request bag.
+   * Apps register their state via `setupApps()` which injects it
+   * into the bag as `app:{name}:state` before each request.
+   *
+   * @example
+   * ```ts
+   * import { RequestContext } from "@decocms/start/sdk/requestContext";
+   * import type { VtexState } from "@decocms/apps/vtex/mod";
+   *
+   * const vtex = RequestContext.getAppState<VtexState>("vtex");
+   * if (vtex) console.log(vtex.config.account);
+   * ```
+   */
+  getAppState<T>(appName: string): T | undefined {
+    const ctx = storage.getStore();
+    return ctx?.bag.get(`app:${appName}:state`) as T | undefined;
+  },
+};

package/src/sdk/requestContextStorage.browser.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+// Import the browser stub explicitly by path. Vitest (no "browser" export
+// condition) would otherwise resolve `@decocms/blocks/sdk/requestContextStorage`
+// to the real `node:async_hooks`-backed module; here we assert the client-safe
+// stand-in that Next.js's client webpack compiler selects via the "browser"
+// export condition behaves exactly like the real storage does outside a request
+// scope.
+import { storage } from "./requestContextStorage.browser";
+
+describe("requestContextStorage.browser (client-safe stub)", () => {
+  it("getStore() returns undefined — no per-request async context on the client", () => {
+    expect(storage.getStore()).toBeUndefined();
+  });
+
+  it("run() invokes the callback inline and returns its value", () => {
+    let ran = false;
+    const result = storage.run({} as never, () => {
+      ran = true;
+      return 42;
+    });
+    expect(ran).toBe(true);
+    expect(result).toBe(42);
+  });
+
+  it("run() does not establish a store — getStore() is still undefined inside the callback", () => {
+    const inside = storage.run({} as never, () => storage.getStore());
+    expect(inside).toBeUndefined();
+  });
+});

package/src/sdk/requestContextStorage.browser.ts

@@ -0,0 +1,43 @@
+/**
+ * Browser-bundle stand-in for the `node:async_hooks`-backed request storage in
+ * `./requestContextStorage`. Selected automatically by bundlers that set the
+ * `"browser"` export condition (Next.js / webpack client compiler, Vite client
+ * build) via the conditional `exports` entry in `packages/blocks/package.json`.
+ *
+ * There is no per-request async context on the client, so this backend simply
+ * reports "no active store". Every `RequestContext` accessor built on top of it
+ * therefore behaves exactly as the real implementation does when called outside
+ * a request scope:
+ *   - `RequestContext.current` / `requestId` → `null`
+ *   - `RequestContext.request` / `signal` / `responseHeaders` → throw
+ *   - `RequestContext.device` → `"desktop"`, `isBot` → `false`, `elapsed` → `0`
+ *   - `RequestContext.fetch` → falls back to `globalThis.fetch`
+ *
+ * That is exactly the fall-through the sole client-reachable consumer
+ * (`resolveDeviceFromRuntime` in `./useDevice`) relies on: `current === null`
+ * → use the `navigator.userAgent` client path. Nothing on the client ever
+ * establishes a request scope, so `run()` never needs real async propagation —
+ * it just invokes the callback inline.
+ *
+ * `RequestContextStorageBackend` is imported `type`-only from the real
+ * `./requestContextStorage` module — this is erased entirely at compile time
+ * (by tsc and by the SWC pass Next.js runs before webpack ever sees the
+ * module graph), so it does NOT drag `node:async_hooks` back into this file's
+ * runtime output. Annotating `storage` with it means this stub and the real
+ * `AsyncLocalStorage`-backed implementation are compiler-checked against the
+ * exact same narrow surface — if one drifts (e.g. `requestContext.ts` starts
+ * calling a method neither backend exposes), `tsc` fails here, not silently
+ * at runtime on the client.
+ */
+
+import type { RequestContextData } from "./requestContext";
+import type { RequestContextStorageBackend } from "./requestContextStorage";
+
+export const storage: RequestContextStorageBackend = {
+  getStore(): RequestContextData | undefined {
+    return undefined;
+  },
+  run<R>(_store: RequestContextData, fn: () => R): R {
+    return fn();
+  },
+};

package/src/sdk/requestContextStorage.ts

@@ -0,0 +1,35 @@
+/**
+ * Node/Workers implementation of the per-request storage backend for
+ * `RequestContext` (see `./requestContext`).
+ *
+ * This is the ONE module in the `requestContext` graph that touches
+ * `node:async_hooks`. It is split out from `requestContext.ts` so that
+ * bundlers building for a browser target can swap it for the no-op stub in
+ * `./requestContextStorage.browser` via the `"browser"` export condition in
+ * `packages/blocks/package.json` — without that condition, Next.js's client
+ * webpack compiler tries to resolve the `node:async_hooks` specifier for a
+ * non-Node target and fails the build with `UnhandledSchemeError`, even though
+ * `AsyncLocalStorage` is only ever meaningfully used server-side.
+ *
+ * Requires `nodejs_compat` in wrangler.jsonc (already enabled) on Workers.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { RequestContextData } from "./requestContext";
+
+/**
+ * The narrow surface `requestContext.ts` actually calls (`storage.getStore()`
+ * / `storage.run(ctx, fn)`). Exporting `storage` typed as this interface —
+ * rather than letting it infer the full `AsyncLocalStorage<RequestContextData>`
+ * type — means `requestContext.ts` only ever sees these two members,
+ * regardless of which backend (this file or `./requestContextStorage.browser`)
+ * a given bundler's export condition resolves to. If `requestContext.ts` is
+ * ever edited to call another `AsyncLocalStorage` method (e.g. `enterWith`,
+ * `exit`, `disable`), that becomes an immediate compile error at the call
+ * site — forcing whoever adds it to widen this type here AND add the method
+ * to the browser stub, instead of silently working against the real backend
+ * while quietly breaking on the client.
+ */
+export type RequestContextStorageBackend = Pick<AsyncLocalStorage<RequestContextData>, "run" | "getStore">;
+
+export const storage: RequestContextStorageBackend = new AsyncLocalStorage<RequestContextData>();

package/src/sdk/retry.ts

@@ -0,0 +1,45 @@
+export const CONNECTION_CLOSED_MESSAGE = "connection closed before message completed";
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Simple retry utility — replaces cockatiel to avoid module-level AbortController
+ * (cockatiel's abort.js creates new AbortController() at module scope, which is
+ * forbidden in Cloudflare Workers global scope).
+ *
+ * Retries up to maxAttempts when the error matches the predicate.
+ * Uses exponential backoff: delay = min(initialDelay * exponent^attempt, maxDelay).
+ */
+export function retryExceptionOr500() {
+  return {
+    execute: async <T>(fn: () => Promise<T>): Promise<T> => {
+      const maxAttempts = 3;
+      const initialDelay = 100;
+      const maxDelay = 5000;
+      const exponent = 2;
+
+      let lastErr: unknown;
+      for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        try {
+          return await fn();
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          if (!message.includes(CONNECTION_CLOSED_MESSAGE)) {
+            throw err;
+          }
+          lastErr = err;
+          try {
+            console.error("retrying...", err);
+          } catch (_) {}
+          if (attempt < maxAttempts - 1) {
+            const delay = Math.min(initialDelay * Math.pow(exponent, attempt), maxDelay);
+            await sleep(delay);
+          }
+        }
+      }
+      throw lastErr;
+    },
+  };
+}