@decocms/nextjs 8.1.0-next.0 → 8.5.0

package/src/routeHandlers.test.ts

@@ -1,243 +0,0 @@
-// @vitest-environment node
-//
-// Route Handlers run server-side with no DOM (same rationale as
-// setup.test.ts in this package). This matters concretely here: jsdom's
-// bundled Request polyfill does not reproduce Node/edge's Request-as-init
-// body-stream forwarding (`new Request(url, existingRequest)`) — under
-// jsdom the body-forwarding test below silently loses the body. Node's
-// native Request (used in this environment, and in the real Next.js
-// runtime) preserves it, which is what the previews-rebuild code path
-// relies on.
-import { beforeEach, describe, expect, it, vi } from "vitest";
-
-const mocks = vi.hoisted(() => ({
-  handleDecofileRead: vi.fn(async () => new Response("decofile")),
-  handleDecofileReload: vi.fn(async () => new Response("reloaded")),
-  handleInvoke: vi.fn(async () => new Response("invoked")),
-  handleMeta: vi.fn(() => new Response("meta")),
-  handleRender: vi.fn(async (req: Request) => new Response(new URL(req.url).pathname)),
-  setMetaData: vi.fn(),
-  // Real corsHeaders shape (mirrors blocks-admin/src/admin/cors.ts) so the
-  // CORS assertions below test genuine header propagation, not a stub echo.
-  corsHeaders: vi.fn((req: Request) => ({
-    "Access-Control-Allow-Origin": req.headers.get("origin") || "*",
-    "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
-    "Access-Control-Allow-Headers": "Content-Type, Authorization, If-None-Match",
-    "Access-Control-Allow-Credentials": "true",
-  })),
-}));
-vi.mock("@decocms/blocks-admin", () => mocks);
-
-import { setMetaData } from "@decocms/blocks-admin";
-import { createDecoRouteHandlers, metaGET } from "./routeHandlers";
-
-describe("routeHandlers (next)", () => {
-  it("metaGET returns the schema response", async () => {
-    setMetaData({ sections: {}, actions: {}, loaders: {} } as any);
-    const response = await metaGET(new Request("https://example.com/live/_meta"));
-    expect(response.status).toBe(200);
-  });
-});
-
-describe("createDecoRouteHandlers", () => {
-  beforeEach(() => vi.clearAllMocks());
-
-  it("runs setup before dispatching and routes decofile GET/POST", async () => {
-    const order: string[] = [];
-    const setup = vi.fn(async () => {
-      order.push("setup");
-    });
-    const { GET, POST } = createDecoRouteHandlers({ setup });
-
-    await GET(new Request("http://x/deco/decofile"));
-    expect(setup).toHaveBeenCalled();
-    expect(mocks.handleDecofileRead).toHaveBeenCalled();
-
-    await POST(new Request("http://x/deco/decofile", { method: "POST" }));
-    expect(mocks.handleDecofileReload).toHaveBeenCalled();
-  });
-
-  it("routes meta, render, and invoke", async () => {
-    const { GET, POST } = createDecoRouteHandlers();
-    await GET(new Request("http://x/deco/meta"));
-    expect(mocks.handleMeta).toHaveBeenCalled();
-    await POST(new Request("http://x/deco/render", { method: "POST" }));
-    expect(mocks.handleRender).toHaveBeenCalled();
-    await POST(new Request("http://x/deco/invoke/site/actions/x", { method: "POST" }));
-    expect(mocks.handleInvoke).toHaveBeenCalled();
-  });
-
-  it("redirects preview GETs to the fixed RSC page and preserves the path and query", async () => {
-    const { GET } = createDecoRouteHandlers();
-    const res = await GET(
-      new Request("http://x/deco/previews/pages-Home-123?props=x&deviceHint=mobile"),
-    );
-
-    expect(res.status).toBe(307);
-    expect(res.headers.get("location")).toBe(
-      "http://x/deco/preview/pages-Home-123?props=x&deviceHint=mobile",
-    );
-    expect(mocks.handleRender).not.toHaveBeenCalled();
-  });
-
-  it("redirects the public /live/previews path to the fixed RSC page", async () => {
-    const { GET } = createDecoRouteHandlers();
-    const res = await GET(
-      new Request("http://x/live/previews/site/sections/Hero.tsx?deviceHint=desktop"),
-    );
-
-    expect(res.status).toBe(307);
-    expect(res.headers.get("location")).toBe(
-      "http://x/deco/preview/site/sections/Hero.tsx?deviceHint=desktop",
-    );
-    expect(mocks.handleRender).not.toHaveBeenCalled();
-  });
-
-  it("keeps preview POSTs on handleRender", async () => {
-    const { POST } = createDecoRouteHandlers();
-    const res = await POST(
-      new Request("http://x/deco/previews/pages-Home-123", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ hello: "world" }),
-      }),
-    );
-
-    expect(res.status).toBe(200);
-    expect(mocks.handleRender).toHaveBeenCalledOnce();
-  });
-
-  it("forwards a POST body through the /deco/previews/* URL rebuild (Request-as-init carries the body stream)", async () => {
-    // Pins the `new Request(rebuilt, request)` semantics documented on the
-    // rebuild line: passing a Request as `init` clones the body stream
-    // without a `duplex` option. A refactor to a plain init object would
-    // throw "duplex option is required" for this POST body.
-    mocks.handleRender.mockImplementationOnce(async (req: Request) => {
-      const body = await req.json();
-      return new Response(JSON.stringify({ pathname: new URL(req.url).pathname, body }));
-    });
-    const { POST } = createDecoRouteHandlers();
-    const res = await POST(
-      new Request("http://x/deco/previews/pages-Home-123", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ hello: "world" }),
-      }),
-    );
-    const json = await res.json();
-    expect(json.pathname).toBe("/live/previews/pages-Home-123");
-    expect(json.body).toEqual({ hello: "world" });
-  });
-
-  it("404s unknown deco paths", async () => {
-    const { GET } = createDecoRouteHandlers();
-    const res = await GET(new Request("http://x/deco/nope"));
-    expect(res.status).toBe(404);
-  });
-
-  // Regression coverage for the rewrite-source paths, not just their
-  // /deco/* destinations: a Next.js App Router route handler reached via a
-  // next.config.js `rewrites()` entry sees `request.url` as the ORIGINAL,
-  // pre-rewrite path (verified empirically against a real `next build` +
-  // `next start`) — NOT the /deco/* destination the rewrite maps to. Every
-  // test above this one only ever constructs an already-/deco/*-shaped
-  // Request, so it would keep passing even if the dispatcher only matched
-  // that form and 404'd every real rewritten request — which is exactly
-  // the bug these tests catch.
-  it("routes the rewrite-source /.decofile path (not just its /deco/decofile destination)", async () => {
-    const { GET, POST } = createDecoRouteHandlers();
-    await GET(new Request("http://x/.decofile"));
-    expect(mocks.handleDecofileRead).toHaveBeenCalled();
-    await POST(new Request("http://x/.decofile", { method: "POST" }));
-    expect(mocks.handleDecofileReload).toHaveBeenCalled();
-  });
-
-  it("routes the rewrite-source /live/_meta path (not just its /deco/meta destination)", async () => {
-    const { GET } = createDecoRouteHandlers();
-    const res = await GET(new Request("http://x/live/_meta"));
-    expect(mocks.handleMeta).toHaveBeenCalled();
-    expect(res.status).not.toBe(404);
-  });
-
-  it("405s POST /live/_meta with Allow: GET (the PRE-rewrite URL form)", async () => {
-    const { POST } = createDecoRouteHandlers();
-    const res = await POST(new Request("http://x/live/_meta", { method: "POST" }));
-    expect(res.status).toBe(405);
-    expect(res.headers.get("Allow")).toBe("GET");
-    expect(mocks.handleMeta).not.toHaveBeenCalled();
-  });
-
-  it("redirects the rewrite-source /live/previews/* path to the fixed RSC page", async () => {
-    const { GET } = createDecoRouteHandlers();
-    const res = await GET(new Request("http://x/live/previews/pages-Home-123?props=x"));
-    expect(res.status).toBe(307);
-    expect(res.headers.get("location")).toBe("http://x/deco/preview/pages-Home-123?props=x");
-    expect(mocks.handleRender).not.toHaveBeenCalled();
-  });
-
-  it("405s GET /deco/invoke/* with Allow: POST (CSRF protection — see comment on the invoke branch)", async () => {
-    const { GET } = createDecoRouteHandlers();
-    const res = await GET(new Request("http://x/deco/invoke/site/actions/x"));
-    expect(res.status).toBe(405);
-    expect(res.headers.get("Allow")).toBe("POST");
-    expect(mocks.handleInvoke).not.toHaveBeenCalled();
-  });
-
-  it("405s POST /deco/meta with Allow: GET", async () => {
-    const { POST } = createDecoRouteHandlers();
-    const res = await POST(new Request("http://x/deco/meta", { method: "POST" }));
-    expect(res.status).toBe(405);
-    expect(res.headers.get("Allow")).toBe("GET");
-    expect(mocks.handleMeta).not.toHaveBeenCalled();
-  });
-});
-
-describe("createDecoRouteHandlers — CORS (Studio is a cross-origin browser client)", () => {
-  beforeEach(() => vi.clearAllMocks());
-
-  it("answers OPTIONS preflight with 204 + CORS headers, without running setup", async () => {
-    const setup = vi.fn(async () => {});
-    const { OPTIONS } = createDecoRouteHandlers({ setup });
-    const res = await OPTIONS(
-      new Request("http://x/live/_meta", {
-        method: "OPTIONS",
-        headers: {
-          origin: "https://decocms.com",
-          "access-control-request-method": "GET",
-          "access-control-request-headers": "if-none-match",
-        },
-      }),
-    );
-    expect(res.status).toBe(204);
-    expect(res.headers.get("Access-Control-Allow-Origin")).toBe("https://decocms.com");
-    expect(res.headers.get("Access-Control-Allow-Headers")).toContain("If-None-Match");
-    expect(setup).not.toHaveBeenCalled();
-  });
-
-  it("stamps CORS headers on successful responses (meta via pre-rewrite URL)", async () => {
-    const { GET } = createDecoRouteHandlers();
-    const res = await GET(
-      new Request("http://x/live/_meta", { headers: { origin: "https://admin.deco.cx" } }),
-    );
-    expect(await res.text()).toBe("meta");
-    expect(res.headers.get("Access-Control-Allow-Origin")).toBe("https://admin.deco.cx");
-  });
-
-  it("stamps CORS headers on method-gate 405s too", async () => {
-    const { GET } = createDecoRouteHandlers();
-    const res = await GET(
-      new Request("http://x/deco/invoke/site/actions/x", {
-        headers: { origin: "https://decocms.com" },
-      }),
-    );
-    expect(res.status).toBe(405);
-    expect(res.headers.get("Access-Control-Allow-Origin")).toBe("https://decocms.com");
-  });
-
-  it("named exports carry CORS as well (metaGET)", async () => {
-    const res = await metaGET(
-      new Request("http://x/live/_meta", { headers: { origin: "https://decocms.com" } }),
-    );
-    expect(res.headers.get("Access-Control-Allow-Origin")).toBe("https://decocms.com");
-  });
-});

package/src/routeHandlers.ts

@@ -1,227 +0,0 @@
-/**
- * Admin Route Handlers for Next.js App Router.
- *
- * IMPORT THESE FROM `@decocms/nextjs/routeHandlers` IN ROUTE FILES — never
- * from the `@decocms/nextjs` root barrel. Route handlers (app router
- * route.ts files) evaluate their whole module graph against React's
- * react-server build and IGNORE `"use client"` directives (there is no
- * client graph to move a module into). The root barrel also exports the
- * render components (SectionRenderer, DecoRootLayout, ...), whose graph
- * reaches `@decocms/blocks/hooks` — files with module-scope client-React
- * usage (e.g. `class ... extends Component`) that the react-server build
- * does not export. Importing the root barrel from a route file therefore
- * crashes at module evaluation ("...createContext is not a function" /
- * "Class extends value undefined is not a constructor") before the handler
- * ever runs. This subpath keeps the route-handler graph free of all
- * component code.
- */
-import {
-  corsHeaders,
-  handleDecofileRead,
-  handleDecofileReload,
-  handleInvoke,
-  handleMeta,
-  handleRender,
-} from "@decocms/blocks-admin";
-
-/**
- * Stamp the admin CORS headers onto a handler response. The Studio is a
- * cross-origin browser client (decocms.com / admin.deco.cx fetching the
- * site's /live/_meta, /.decofile, ...), and its ETag flow sends
- * `If-None-Match` — a non-simple header, so requests preflight. On
- * TanStack this stamping lives in workerEntry/adminRoutes; on Next.js it
- * lives HERE, since these handlers/dispatcher are the only admin surface.
- * Response headers can be immutable (e.g. a cached/replayed body) — fall
- * back to cloning.
- */
-function withCors(request: Request, response: Response): Response {
-  const cors = corsHeaders(request);
-  try {
-    for (const [k, v] of Object.entries(cors)) response.headers.set(k, v);
-    return response;
-  } catch {
-    const headers = new Headers(response.headers);
-    for (const [k, v] of Object.entries(cors)) headers.set(k, v);
-    return new Response(response.body, {
-      status: response.status,
-      statusText: response.statusText,
-      headers,
-    });
-  }
-}
-
-/** Answer a CORS preflight for the admin protocol. */
-function preflight(request: Request): Response {
-  return new Response(null, { status: 204, headers: corsHeaders(request) });
-}
-
-/** For app/live/_meta/route.ts: `export { metaGET as GET } from "@decocms/nextjs/routeHandlers"` */
-export async function metaGET(request: Request): Promise<Response> {
-  return withCors(request, await handleMeta(request));
-}
-
-/** For app/.decofile/route.ts (or an equivalent rewritten path — Next.js route
- * segments can't literally start with a dot; see Task 9's fixture for the
- * rewrite-rule workaround). */
-export async function decofileGET(request: Request): Promise<Response> {
-  return withCors(request, await handleDecofileRead());
-}
-
-export async function decofilePOST(request: Request): Promise<Response> {
-  return withCors(request, await handleDecofileReload(request));
-}
-
-/** For app/deco/invoke/[...key]/route.ts */
-export async function invokePOST(request: Request): Promise<Response> {
-  return withCors(request, await handleInvoke(request));
-}
-
-/** For app/live/previews/[...path]/route.ts */
-export async function renderGET(request: Request): Promise<Response> {
-  return withCors(request, await handleRender(request));
-}
-
-export async function renderPOST(request: Request): Promise<Response> {
-  return withCors(request, await handleRender(request));
-}
-
-export interface DecoRouteHandlersOptions {
-  /**
-   * Site bootstrap, awaited before every admin request — pass the
-   * ensureSetup returned by createNextSetup (@decocms/nextjs/setup).
-   */
-  setup?: () => Promise<void>;
-}
-
-const PREVIEW_PAGE_PATH = "/deco/preview";
-
-/**
- * Single catch-all dispatcher for the whole Studio admin protocol. Mount
- * at `app/deco/[[...deco]]/route.ts` and wrap next.config with
- * `withDeco()` (@decocms/nextjs/config), whose rewrites map the protocol
- * URLs Next can't express as segments (`/.decofile`, `/live/_meta`,
- * `/live/previews/*`) into `/deco/*`:
- *
- * ```ts
- * import { createDecoRouteHandlers } from "@decocms/nextjs/routeHandlers";
- * import { ensureSetup } from "../../../deco/setup";
- * export const dynamic = "force-dynamic";
- * export const { GET, POST, OPTIONS } = createDecoRouteHandlers({
- *   setup: ensureSetup,
- * });
- * ```
- *
- * `resolveAction` accepts BOTH the rewrite's public source path (e.g.
- * `/.decofile`, `/live/_meta`, `/live/previews/*`) AND the rewrite's own
- * destination path (`/deco/*`) — not just the latter. This is load-bearing:
- * verified empirically against a real `next build && next start` (both
- * dev and production servers) that a Next.js App Router route handler
- * reached via a `next.config.js`-level `rewrites()` entry sees
- * `request.url` (and `NextRequest.nextUrl.pathname`) as the ORIGINAL,
- * pre-rewrite path the client requested — rewrites are transparent to the
- * client and, in this respect, to the handler too. Only a *direct* request
- * to `/deco/*` (bypassing the rewrite, e.g. `/deco/invoke/*`, which has no
- * public alias) arrives with a `/deco/`-prefixed pathname. Matching only
- * the `/deco/*` form (as an earlier version of this dispatcher did) makes
- * every rewritten protocol URL 404 — the dispatcher never sees a
- * `/deco/decofile`-shaped path in that case, it sees `/.decofile` verbatim.
- */
-function resolveAction(pathname: string): string {
-  if (pathname.startsWith("/deco/")) return pathname.slice("/deco/".length);
-  if (pathname === "/.decofile") return "decofile";
-  if (pathname === "/live/_meta") return "meta";
-  if (pathname === "/live/previews") return "previews";
-  if (pathname.startsWith("/live/previews/")) {
-    return `previews/${pathname.slice("/live/previews/".length)}`;
-  }
-  return pathname;
-}
-
-export function createDecoRouteHandlers(options: DecoRouteHandlersOptions = {}): {
-  GET(request: Request): Promise<Response>;
-  POST(request: Request): Promise<Response>;
-  OPTIONS(request: Request): Promise<Response>;
-} {
-  async function dispatch(request: Request): Promise<Response> {
-    // CORS preflight: Studio fetches cross-origin and its ETag flow sends
-    // If-None-Match (non-simple header), so browsers preflight every meta
-    // request. Answer before setup — preflights carry no work and must not
-    // pay (or fail on) the site bootstrap.
-    if (request.method === "OPTIONS") return preflight(request);
-    await options.setup?.();
-
-    const url = new URL(request.url);
-    const action = resolveAction(url.pathname);
-
-    if (action === "decofile") {
-      return request.method === "POST" ? handleDecofileReload(request) : handleDecofileRead();
-    }
-    if (action === "meta") {
-      // GET only: this is a read-only schema endpoint, no legitimate POST use.
-      if (request.method !== "GET") {
-        return new Response(JSON.stringify({ error: "Method not allowed: meta is GET-only" }), {
-          status: 405,
-          headers: { "Content-Type": "application/json", Allow: "GET" },
-        });
-      }
-      return handleMeta(request);
-    }
-    if (action === "render") return handleRender(request);
-    if (action.startsWith("invoke/")) {
-      // POST only: handleInvoke has no auth of its own and falls back to a
-      // `?props=<json>` query string for GET requests. A GET is a CORS
-      // "simple request" (no preflight), so an unauthenticated
-      // `<img src="https://site/deco/invoke/site/actions/...?props=...">`
-      // on a third-party page would be able to trigger mutating VTEX
-      // actions cross-site (CSRF). The per-route `invokePOST` export this
-      // dispatcher replaces was POST-only for exactly this reason — keep
-      // that restriction here.
-      if (request.method !== "POST") {
-        return new Response(
-          JSON.stringify({ error: "Method not allowed: invoke is POST-only (CSRF protection)" }),
-          {
-            status: 405,
-            headers: { "Content-Type": "application/json", Allow: "POST" },
-          },
-        );
-      }
-      return handleInvoke(request);
-    }
-    if (action === "previews" || action.startsWith("previews/")) {
-      if (request.method === "GET") {
-        const rest = action === "previews" ? "" : action.slice("previews/".length);
-        const target = new URL(url);
-        target.pathname = rest ? `${PREVIEW_PAGE_PATH}/${rest}` : PREVIEW_PAGE_PATH;
-        return Response.redirect(target, 307);
-      }
-
-      // handleRender parses the literal "/live/previews/" prefix.
-      // `resolveAction` above already normalizes BOTH a direct
-      // `/deco/previews/*` hit and a rewritten `/live/previews/*` hit down
-      // to this same `action` shape, so rebuilding unconditionally here is
-      // a no-op in the rewrite case (rebuilt === original) and the
-      // necessary reconstruction in the direct-hit case.
-      const rest = action === "previews" ? "" : action.slice("previews/".length);
-      const rebuilt = new URL(url);
-      rebuilt.pathname = `/live/previews/${rest}`;
-      // `request` (a Request) is passed as the `init` argument here, not a
-      // plain object — the Request-as-init form clones headers/method/body
-      // (including the body *stream*) without needing an explicit `duplex`
-      // option. Rewriting this as `new Request(rebuilt, { ...request })` or
-      // any plain-object init would throw "duplex option is required" for
-      // POST bodies with a body stream — see the test below that posts a
-      // JSON body through this branch and asserts it still parses.
-      return handleRender(new Request(rebuilt, request));
-    }
-    return new Response(JSON.stringify({ error: `Unknown deco route: ${url.pathname}` }), {
-      status: 404,
-      headers: { "Content-Type": "application/json" },
-    });
-  }
-
-  async function dispatchWithCors(request: Request): Promise<Response> {
-    return withCors(request, await dispatch(request));
-  }
-
-  return { GET: dispatchWithCors, POST: dispatchWithCors, OPTIONS: dispatchWithCors };
-}