@avocadostudio-ai/site-sdk 0.5.1 → 0.7.0

package/dist/middleware.js

@@ -1,4 +1,10 @@
 import { createEditorProxy } from "./proxy.js";
+/*
+ * A Next 15 site reaches for this entry point, and a Next 15 site that already
+ * has a `middleware.ts` needs the two halves rather than the whole factory.
+ * Re-exported here so composing does not mean importing from two subpaths.
+ */
+export { trailingSlashRedirect, editorPreviewRewrite } from "./proxy.js";
 /**
  * Create a Next.js middleware function that rewrites editor/draft requests
  * to a dynamic preview route, keeping the main page route fully static.

package/dist/proxy.d.ts

@@ -93,3 +93,29 @@ export declare function createEditorProxy(options?: EditorProxyOptions): {
         matcher: string[];
     };
 };
+/**
+ * Re-issue the trailing-slash redirect that `skipTrailingSlashRedirect` turned
+ * off, or `null` when the URL is already canonical.
+ *
+ * Exported because a site that already has a `middleware.ts` cannot use
+ * `createEditorProxy` as its whole middleware and has to compose — and the one
+ * line worth not writing twice is the first one below.
+ *
+ * ```ts
+ * export function middleware(request: NextRequest) {
+ *   const canonical = trailingSlashRedirect(request)
+ *   if (canonical) return canonical
+ *   return editorPreviewRewrite(request) ?? myOwnMiddleware(request)
+ * }
+ * ```
+ */
+export declare function trailingSlashRedirect(request: NextRequest): NextResponse | null;
+/**
+ * Rewrite an editor request to the dynamic preview route, or `null` when the
+ * request is not one — which is the caller's cue to run its own middleware
+ * rather than a decision to pass the request through.
+ *
+ * The half of `createEditorProxy` a site with its own middleware needs; see
+ * {@link trailingSlashRedirect} for the composition.
+ */
+export declare function editorPreviewRewrite(request: NextRequest, options?: Pick<EditorProxyOptions, "previewRoute" | "editorParam" | "draftCookie">): NextResponse | null;

package/dist/proxy.js

@@ -1,5 +1,6 @@
 import { NextResponse } from "next/server";
 import { DEFAULT_PREVIEW_ROUTE, buildEditorMatcher } from "./editor-matcher.js";
+import { EDITOR_RENDER_HEADER } from "./editor-render.js";
 export { DEFAULT_PREVIEW_ROUTE, buildEditorMatcher } from "./editor-matcher.js";
 /**
  * Create a Next.js proxy function that rewrites editor/draft requests
@@ -33,8 +34,6 @@ export { DEFAULT_PREVIEW_ROUTE, buildEditorMatcher } from "./editor-matcher.js";
  */
 export function createEditorProxy(options) {
     const previewRoute = options?.previewRoute ?? DEFAULT_PREVIEW_ROUTE;
-    const editorParam = options?.editorParam ?? "__editor";
-    const draftCookie = options?.draftCookie === undefined ? "__prerender_bypass" : options.draftCookie;
     const trailingSlash = options?.trailingSlash ?? false;
     function proxy(request) {
         /*
@@ -45,32 +44,95 @@ export function createEditorProxy(options) {
          * publishes only at `/about/`.
          */
         if (trailingSlash) {
-            /*
-             * Built from `request.url`, not from `request.nextUrl.clone()`. NextURL
-             * normalises a trailing slash back *off* when it stringifies, so a
-             * redirect built from a clone points at the URL it is trying to leave —
-             * a redirect loop, and one that only a browser would ever have shown us.
-             * A plain URL does no normalising. It also keeps `basePath`, which
-             * `nextUrl.pathname` has already stripped.
-             */
-            const url = new URL(request.url);
-            if (url.pathname.length > 1 && !url.pathname.endsWith("/")) {
-                url.pathname = `${url.pathname}/`;
-                // 308, not 307: the method is preserved *and* the redirect is
-                // permanent, which is what Next's own trailing-slash redirect sends
-                // and what the site's existing search rankings were built on.
-                return NextResponse.redirect(url, 308);
-            }
-        }
-        const isEditor = request.nextUrl.searchParams.get(editorParam) === "1";
-        const hasDraftCookie = draftCookie !== false && request.cookies.has(draftCookie);
-        if (isEditor || hasDraftCookie) {
-            const url = request.nextUrl.clone();
-            url.pathname = `${previewRoute}${url.pathname}`;
-            return NextResponse.rewrite(url);
+            const redirect = trailingSlashRedirect(request);
+            if (redirect)
+                return redirect;
         }
-        return NextResponse.next();
+        return editorPreviewRewrite(request, options) ?? NextResponse.next();
     }
     const config = { matcher: [buildEditorMatcher(previewRoute)] };
     return { proxy, config };
 }
+/**
+ * Re-issue the trailing-slash redirect that `skipTrailingSlashRedirect` turned
+ * off, or `null` when the URL is already canonical.
+ *
+ * Exported because a site that already has a `middleware.ts` cannot use
+ * `createEditorProxy` as its whole middleware and has to compose — and the one
+ * line worth not writing twice is the first one below.
+ *
+ * ```ts
+ * export function middleware(request: NextRequest) {
+ *   const canonical = trailingSlashRedirect(request)
+ *   if (canonical) return canonical
+ *   return editorPreviewRewrite(request) ?? myOwnMiddleware(request)
+ * }
+ * ```
+ */
+export function trailingSlashRedirect(request) {
+    /*
+     * Built from `request.url`, not from `request.nextUrl.clone()`. NextURL
+     * normalises a trailing slash back *off* when it stringifies, so a redirect
+     * built from a clone points at the URL it is trying to leave — every page on
+     * the site enters an infinite redirect, and only in a browser: `curl`
+     * without `-L` sees one perfectly ordinary 308. A plain URL does no
+     * normalising. It also keeps `basePath`, which `nextUrl.pathname` has
+     * already stripped.
+     */
+    const url = new URL(request.url);
+    const { pathname } = url;
+    if (pathname.length <= 1 || pathname.endsWith("/"))
+        return null;
+    /*
+     * The set that must never gain a trailing slash. `createEditorProxy`'s own
+     * matcher already excludes all of it, so these are no-ops there — they are
+     * for the hand-composed case, where the site's matcher is its own and is
+     * usually wider. Redirecting `/api/editor/blocks` to `/api/editor/blocks/`
+     * here would re-create, by hand, the exact 308 that
+     * `skipTrailingSlashRedirect` was turned on to stop.
+     */
+    if (pathname.startsWith("/api/") || pathname.startsWith("/_next/"))
+        return null;
+    if (pathname.slice(pathname.lastIndexOf("/") + 1).includes("."))
+        return null;
+    url.pathname = `${pathname}/`;
+    // 308, not 307: the method is preserved *and* the redirect is permanent,
+    // which is what Next's own trailing-slash redirect sends and what the site's
+    // existing search rankings were built on.
+    return NextResponse.redirect(url, 308);
+}
+/**
+ * Rewrite an editor request to the dynamic preview route, or `null` when the
+ * request is not one — which is the caller's cue to run its own middleware
+ * rather than a decision to pass the request through.
+ *
+ * The half of `createEditorProxy` a site with its own middleware needs; see
+ * {@link trailingSlashRedirect} for the composition.
+ */
+export function editorPreviewRewrite(request, options) {
+    const previewRoute = options?.previewRoute ?? DEFAULT_PREVIEW_ROUTE;
+    const editorParam = options?.editorParam ?? "__editor";
+    const draftCookie = options?.draftCookie === undefined ? "__prerender_bypass" : options.draftCookie;
+    const isEditor = request.nextUrl.searchParams.get(editorParam) === "1";
+    const hasDraftCookie = draftCookie !== false && request.cookies.has(draftCookie);
+    if (!isEditor && !hasDraftCookie)
+        return null;
+    const url = request.nextUrl.clone();
+    url.pathname = `${previewRoute}${url.pathname}`;
+    /*
+     * The one fact a layout can get at.
+     *
+     * A page learns it is being previewed from `resolveEditorContext(searchParams)`.
+     * A layout receives no `searchParams`, and the root layout is exactly where a
+     * site mounts its consent banner, analytics and tag manager — so every
+     * integration loads all three into the editor iframe until somebody notices
+     * the pageviews. Stamping the rewritten request lets `isEditorRender()` answer
+     * in a layout without the site threading anything down to it.
+     *
+     * Set, not appended: a client-supplied header of the same name is replaced, so
+     * what a layout reads here is the proxy's own answer.
+     */
+    const headers = new Headers(request.headers);
+    headers.set(EDITOR_RENDER_HEADER, "1");
+    return NextResponse.rewrite(url, { request: { headers } });
+}

package/dist/proxy.test.js

@@ -1,7 +1,7 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { NextRequest } from "next/server";
-import { buildEditorMatcher, createEditorProxy, DEFAULT_PREVIEW_ROUTE } from "./proxy.js";
+import { NextRequest, NextResponse } from "next/server";
+import { buildEditorMatcher, createEditorProxy, editorPreviewRewrite, trailingSlashRedirect, DEFAULT_PREVIEW_ROUTE } from "./proxy.js";
 import { createEditorMiddleware } from "./middleware.js";
 /*
  * The rewrite that keeps the published route static and sends editor traffic to
@@ -121,3 +121,62 @@ test("draftCookie: false leaves Next's draft cookie to whoever else is using it"
     assert.equal(rewriteOf(proxy(request("https://site.test/about", "__prerender_bypass=abc"))), null, "a Sanity or Contentful preview must not be hijacked into Avocado's route");
     assert.equal(rewriteOf(proxy(request("https://site.test/about?__editor=1"))), "https://site.test/preview-draft/about?__editor=1", "the explicit editor parameter still works — that is the whole point of the opt-out");
 });
+/*
+ * The two halves, on their own.
+ *
+ * A site that already has a `middleware.ts` cannot hand the whole file to
+ * `createEditorProxy` and has to compose — which until now meant re-deriving
+ * the trailing-slash redirect from the docs. One integration did, and wrote
+ * `request.nextUrl.clone()`, because that is what every Next example uses for
+ * a URL you intend to modify. A `NextURL` re-applies trailing-slash
+ * normalisation when it serialises, so the redirect stripped the slash it had
+ * just added and pointed at the URL it came from: every page on the site in an
+ * infinite redirect, reproducing only in a browser. `curl` without `-L` sees
+ * one perfectly ordinary 308, which is how it survived a session and a half.
+ */
+test("the redirect is built from request.url, not from a NextURL that would undo it", () => {
+    const response = trailingSlashRedirect(request("https://site.test/bern"));
+    assert.equal(response?.status, 308);
+    assert.equal(response?.headers.get("location"), "https://site.test/bern/", "a location without the slash is the loop: the browser asks again and gets the same answer");
+});
+test("an already-canonical URL, the root, and a file are left alone", () => {
+    assert.equal(trailingSlashRedirect(request("https://site.test/bern/")), null);
+    assert.equal(trailingSlashRedirect(request("https://site.test/")), null, "redirecting / never terminates");
+    assert.equal(trailingSlashRedirect(request("https://site.test/logo.svg")), null);
+});
+test("the API routes are never redirected, whatever the caller's matcher says", () => {
+    /*
+     * The proxy's own matcher excludes these, but a hand-composed middleware
+     * brings its own matcher and it is usually wider. A slash added here
+     * re-creates by hand the exact 308 on `/api/editor/*` that
+     * `skipTrailingSlashRedirect` was turned on to stop — and the symptom is a
+     * CORS error that names nothing.
+     */
+    assert.equal(trailingSlashRedirect(request("https://site.test/api/editor/blocks")), null);
+    assert.equal(trailingSlashRedirect(request("https://site.test/_next/static/chunk")), null);
+});
+test("the redirect keeps the query string when called directly too", () => {
+    const response = trailingSlashRedirect(request("https://site.test/bern?__editor=1"));
+    assert.equal(response?.headers.get("location"), "https://site.test/bern/?__editor=1");
+});
+test("editorPreviewRewrite answers null for a visitor, so the caller runs its own middleware", () => {
+    assert.equal(editorPreviewRewrite(request("https://site.test/about")), null, "null is 'not mine', not 'pass this through' — a composing caller has its own work to do");
+    assert.equal(rewriteOf(editorPreviewRewrite(request("https://site.test/about?__editor=1"))), "https://site.test/preview-draft/about?__editor=1");
+});
+test("the composed form behaves like the factory it was extracted from", () => {
+    const { proxy } = createEditorProxy({ trailingSlash: true });
+    const compose = (r) => trailingSlashRedirect(r) ?? editorPreviewRewrite(r) ?? NextResponse.next();
+    for (const url of [
+        "https://site.test/bern",
+        "https://site.test/bern/",
+        "https://site.test/bern?__editor=1",
+        "https://site.test/bern/?__editor=1",
+        "https://site.test/"
+    ]) {
+        const fromFactory = proxy(request(url));
+        const fromParts = compose(request(url));
+        assert.equal(fromParts.status, fromFactory.status, url);
+        assert.equal(fromParts.headers.get("location"), fromFactory.headers.get("location"), url);
+        assert.equal(rewriteOf(fromParts), rewriteOf(fromFactory), url);
+    }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/site-sdk",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,6 +26,21 @@
       "import": "./dist/markers.js",
       "default": "./dist/markers.js"
     },
+    "./lens": {
+      "types": "./dist/lens/index.d.ts",
+      "import": "./dist/lens/index.js",
+      "default": "./dist/lens/index.js"
+    },
+    "./lens/storyblok": {
+      "types": "./dist/lens/storyblok.d.ts",
+      "import": "./dist/lens/storyblok.js",
+      "default": "./dist/lens/storyblok.js"
+    },
+    "./lens/sanity": {
+      "types": "./dist/lens/sanity.d.ts",
+      "import": "./dist/lens/sanity.js",
+      "default": "./dist/lens/sanity.js"
+    },
     "./blocks": {
       "types": "./dist/blocks.d.ts",
       "import": "./dist/blocks.js",
@@ -122,16 +137,17 @@
   ],
   "dependencies": {
     "zod": "^4.3.6",
-    "@avocadostudio-ai/blocks": "^0.5.1",
-    "@avocadostudio-ai/preview-adapter": "^0.5.1",
-    "@avocadostudio-ai/shared": "^0.5.1"
+    "@avocadostudio-ai/blocks": "^0.7.0",
+    "@avocadostudio-ai/richtext": "^0.7.0",
+    "@avocadostudio-ai/shared": "^0.7.0",
+    "@avocadostudio-ai/preview-adapter": "^0.7.0"
   },
   "peerDependencies": {
     "next": ">=15.0.0",
     "react": ">=19.0.0",
     "react-dom": ">=19.0.0",
     "better-sqlite3": ">=12.0.0",
-    "@avocadostudio-ai/orchestrator-core": "^0.5.1"
+    "@avocadostudio-ai/orchestrator-core": "^0.7.0"
   },
   "peerDependenciesMeta": {
     "@avocadostudio-ai/orchestrator-core": {