@avocadostudio-ai/site-sdk 0.1.0 → 0.2.1

package/dist/proxy.d.ts

@@ -0,0 +1,95 @@
+import { NextResponse, type NextRequest } from "next/server";
+export { DEFAULT_PREVIEW_ROUTE, buildEditorMatcher } from "./editor-matcher.ts";
+/**
+ * Options for the editor proxy factory.
+ */
+export type EditorProxyOptions = {
+    /**
+     * The internal route prefix that the dynamic editor/draft page lives under.
+     * @default "/preview-draft"
+     */
+    previewRoute?: string;
+    /**
+     * Query parameter that signals an editor iframe request.
+     * @default "__editor"
+     */
+    editorParam?: string;
+    /**
+     * Name of the Next.js draft-mode bypass cookie, or `false` to ignore cookies
+     * entirely and key the rewrite on {@link EditorProxyOptions.editorParam} alone.
+     *
+     * The cookie is how navigation *inside* the editor iframe stays in draft mode:
+     * a link click carries no `__editor=1`, so without it the second page a user
+     * visits renders published content.
+     *
+     * But the cookie is Next's own, and it is not Avocado's to claim. Any other
+     * feature that calls `draftMode().enable()` sets the same
+     * `__prerender_bypass` — Sanity's Presentation tool and Contentful's live
+     * preview both do — and every one of *their* preview requests then lands on
+     * Avocado's preview route. On a site that already had Draft Mode before it had
+     * Avocado, pass `draftCookie: false` and the two stop fighting over it.
+     *
+     * @default "__prerender_bypass"
+     */
+    draftCookie?: string | false;
+    /**
+     * Set this to `true` on a site whose `next.config` sets `trailingSlash: true`.
+     *
+     * Such a site cannot talk to the editor until it *stops* letting Next issue
+     * the trailing-slash redirect. Next applies that 308 to `/api/*` as well, so
+     * `/api/editor/blocks` answers `308 → /api/editor/blocks/` — and while `fetch`
+     * follows a 308, a browser does **not** follow a redirect on a CORS preflight.
+     * The editor calls those routes from its own origin, so every editor API call
+     * fails before the request is made. A middleware rewrite cannot repair it
+     * either: Next's trailing-slash redirect runs *before* middleware.
+     *
+     * The fix is `skipTrailingSlashRedirect: true` — which `withAvocado` sets for
+     * you as soon as it sees `trailingSlash: true` — plus re-issuing the redirect
+     * by hand for everything that is not an API route. This flag is that second
+     * half, and the two must be turned on together: the config half alone stops a
+     * site redirecting to its canonical URLs.
+     *
+     * Only page paths are affected. The proxy's matcher already excludes `/api`,
+     * `_next` and anything with a file extension, which is exactly the set that
+     * should never have gained a trailing slash to begin with.
+     *
+     * @default false
+     */
+    trailingSlash?: boolean;
+};
+/**
+ * Create a Next.js proxy function that rewrites editor/draft requests
+ * to a dynamic preview route, keeping the main page route fully static.
+ *
+ * Next.js 16 renamed the `middleware` file convention to `proxy`. Usage in
+ * `proxy.ts` — note that `config` must be written as a literal, because Next 16
+ * rejects both `export const { proxy, config } = createEditorProxy()` and
+ * `export const config = editor.config` with "Next.js can't recognize the
+ * exported `config` field in route. It needs to be a static object":
+ *
+ * ```ts
+ * import { createEditorProxy } from "@avocadostudio-ai/site-sdk/proxy"
+ *
+ * export const proxy = createEditorProxy().proxy
+ *
+ * export const config = {
+ *   matcher: ["/((?!_next|preview-draft|api|favicon\\.ico|icon\\.svg|logos/|generated-images/|.*\\.).*)"],
+ * }
+ * ```
+ *
+ * On Next.js 15 the file is still called `middleware.ts` and the destructured
+ * form works — see `createEditorMiddleware` in
+ * `@avocadostudio-ai/site-sdk/middleware`.
+ *
+ * The returned `config` is kept for that Next 15 path and for tests; on Next 16
+ * inline the literal instead. {@link buildEditorMatcher} produces the string.
+ *
+ * The rewrite only reads the URL and cookies, so it runs unchanged on the
+ * Node.js runtime that `proxy` mandates.
+ */
+export declare function createEditorProxy(options?: EditorProxyOptions): {
+    proxy: (request: NextRequest) => NextResponse<unknown>;
+    config: {
+        matcher: string[];
+    };
+};

package/dist/proxy.js

@@ -0,0 +1,76 @@
+import { NextResponse } from "next/server";
+import { DEFAULT_PREVIEW_ROUTE, buildEditorMatcher } from "./editor-matcher.js";
+export { DEFAULT_PREVIEW_ROUTE, buildEditorMatcher } from "./editor-matcher.js";
+/**
+ * Create a Next.js proxy function that rewrites editor/draft requests
+ * to a dynamic preview route, keeping the main page route fully static.
+ *
+ * Next.js 16 renamed the `middleware` file convention to `proxy`. Usage in
+ * `proxy.ts` — note that `config` must be written as a literal, because Next 16
+ * rejects both `export const { proxy, config } = createEditorProxy()` and
+ * `export const config = editor.config` with "Next.js can't recognize the
+ * exported `config` field in route. It needs to be a static object":
+ *
+ * ```ts
+ * import { createEditorProxy } from "@avocadostudio-ai/site-sdk/proxy"
+ *
+ * export const proxy = createEditorProxy().proxy
+ *
+ * export const config = {
+ *   matcher: ["/((?!_next|preview-draft|api|favicon\\.ico|icon\\.svg|logos/|generated-images/|.*\\.).*)"],
+ * }
+ * ```
+ *
+ * On Next.js 15 the file is still called `middleware.ts` and the destructured
+ * form works — see `createEditorMiddleware` in
+ * `@avocadostudio-ai/site-sdk/middleware`.
+ *
+ * The returned `config` is kept for that Next 15 path and for tests; on Next 16
+ * inline the literal instead. {@link buildEditorMatcher} produces the string.
+ *
+ * The rewrite only reads the URL and cookies, so it runs unchanged on the
+ * Node.js runtime that `proxy` mandates.
+ */
+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) {
+        /*
+         * Before anything else, and deliberately: this stands in for a redirect
+         * Next would have issued before middleware ran, so a request that should
+         * never have been served at this URL must not be served at it here either.
+         * Rewriting first would answer `/about?__editor=1` with content the site
+         * 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);
+        }
+        return NextResponse.next();
+    }
+    const config = { matcher: [buildEditorMatcher(previewRoute)] };
+    return { proxy, config };
+}

package/dist/proxy.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/proxy.test.js

@@ -0,0 +1,123 @@
+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 { createEditorMiddleware } from "./middleware.js";
+/*
+ * The rewrite that keeps the published route static and sends editor traffic to
+ * the dynamic one. It is the single piece of Next config every integrator has
+ * to copy, and until now nothing exercised it — the contract in the READMEs
+ * (`export const { middleware, config } = ...`) turned out not to work on
+ * Next 16 at all, and no test noticed.
+ */
+const rewriteOf = (response) => response.headers.get("x-middleware-rewrite");
+const request = (url, cookie) => new NextRequest(url, cookie ? { headers: { cookie } } : undefined);
+test("an editor request is rewritten to the preview route", () => {
+    const { proxy } = createEditorProxy();
+    const rewrite = rewriteOf(proxy(request("https://site.test/about?__editor=1")));
+    assert.equal(rewrite, "https://site.test/preview-draft/about?__editor=1");
+});
+test("a draft-mode cookie is rewritten even without the query parameter", () => {
+    const { proxy } = createEditorProxy();
+    const rewrite = rewriteOf(proxy(request("https://site.test/about", "__prerender_bypass=abc")));
+    assert.equal(rewrite, "https://site.test/preview-draft/about");
+});
+test("an ordinary visitor is passed straight through", () => {
+    const { proxy } = createEditorProxy();
+    const response = proxy(request("https://site.test/about"));
+    assert.equal(rewriteOf(response), null, "a published page must not be rewritten to the dynamic route");
+    assert.equal(response.headers.get("x-middleware-next"), "1");
+});
+test("__editor with any value other than 1 is not an editor request", () => {
+    const { proxy } = createEditorProxy();
+    assert.equal(rewriteOf(proxy(request("https://site.test/?__editor=0"))), null);
+});
+test("the preview route and cookie name can be overridden together", () => {
+    const { proxy, config } = createEditorProxy({
+        previewRoute: "/draft",
+        editorParam: "edit",
+        draftCookie: "my_bypass",
+    });
+    assert.equal(rewriteOf(proxy(request("https://site.test/x?edit=1"))), "https://site.test/draft/x?edit=1");
+    assert.equal(rewriteOf(proxy(request("https://site.test/x", "my_bypass=1"))), "https://site.test/draft/x");
+    assert.match(config.matcher[0], /draft/);
+});
+test("the matcher skips the preview route itself, or the rewrite would loop", () => {
+    const matcher = new RegExp(`^${buildEditorMatcher()}$`);
+    assert.equal(matcher.test("/preview-draft/about"), false);
+    assert.equal(matcher.test("/_next/static/chunk.js"), false);
+    assert.equal(matcher.test("/api/editor/pages"), false);
+    assert.equal(matcher.test("/favicon.ico"), false);
+    assert.equal(matcher.test("/about"), true);
+    assert.equal(matcher.test("/"), true);
+});
+test("a custom preview route is escaped into the matcher", () => {
+    const matcher = new RegExp(`^${buildEditorMatcher("/draft.preview")}$`);
+    assert.equal(matcher.test("/draft.preview/about"), false);
+    // The `.` is escaped, so it does not match any character.
+    assert.equal(matcher.test("/draftxpreview/about"), true);
+});
+test("the deprecated middleware entry point is the same rewrite under the old name", () => {
+    /*
+     * Kept working for Next 15 sites, where `export const { middleware, config }`
+     * still parses. On Next 16 the file is `proxy.ts` and `config` has to be a
+     * literal — see `createEditorProxy`.
+     */
+    const { middleware, config } = createEditorMiddleware();
+    assert.equal(rewriteOf(middleware(request("https://site.test/about?__editor=1"))), "https://site.test/preview-draft/about?__editor=1");
+    assert.deepEqual(config, createEditorProxy().config);
+});
+test("DEFAULT_PREVIEW_ROUTE is what the factory actually defaults to", () => {
+    assert.equal(rewriteOf(createEditorProxy().proxy(request("https://site.test/a?__editor=1"))), `https://site.test${DEFAULT_PREVIEW_ROUTE}/a?__editor=1`);
+});
+/*
+ * `trailingSlash: true` and the editor could not coexist. Next applies its 308
+ * to `/api/*` too, and a browser will not follow a redirect on a CORS preflight,
+ * so every editor API call failed before it was sent. `withAvocado` turns the
+ * redirect off; these pin the half that puts it back.
+ */
+const locationOf = (response) => response.headers.get("location");
+test("a trailing-slash site gets back the redirect the config turned off", () => {
+    const { proxy } = createEditorProxy({ trailingSlash: true });
+    const response = proxy(request("https://site.test/about"));
+    assert.equal(response.status, 308, "308, like Next's own — the site's rankings were built on a permanent redirect");
+    assert.equal(locationOf(response), "https://site.test/about/");
+});
+test("the redirect keeps the query string, or the editor loses its own parameter", () => {
+    const { proxy } = createEditorProxy({ trailingSlash: true });
+    assert.equal(locationOf(proxy(request("https://site.test/about?__editor=1"))), "https://site.test/about/?__editor=1");
+});
+test("an already-canonical path is rewritten, not redirected into a loop", () => {
+    const { proxy } = createEditorProxy({ trailingSlash: true });
+    const response = proxy(request("https://site.test/about/?__editor=1"));
+    assert.equal(response.status, 200);
+    assert.equal(rewriteOf(response), "https://site.test/preview-draft/about/?__editor=1");
+});
+test("the root is already canonical — redirecting it would never terminate", () => {
+    const { proxy } = createEditorProxy({ trailingSlash: true });
+    const response = proxy(request("https://site.test/?__editor=1"));
+    assert.equal(response.status, 200, "`/` already ends in a slash; redirecting it is a loop");
+    // Asserted as a prefix: the rewrite target goes through NextURL, which
+    // normalises the trailing slash according to the app's own config.
+    assert.match(rewriteOf(response) ?? "", /^https:\/\/site\.test\/preview-draft/);
+});
+test("the redirect comes before the rewrite, so no page is served at a URL the site does not publish", () => {
+    const { proxy } = createEditorProxy({ trailingSlash: true });
+    const response = proxy(request("https://site.test/about?__editor=1"));
+    assert.equal(rewriteOf(response), null, "an unslashed editor URL must redirect first, not render");
+});
+test("a site that never asked for trailing slashes is never redirected", () => {
+    const { proxy } = createEditorProxy();
+    assert.equal(proxy(request("https://site.test/about")).status, 200);
+    assert.equal(locationOf(proxy(request("https://site.test/about"))), null);
+});
+/*
+ * `__prerender_bypass` is Next's cookie, not Avocado's. A site that already used
+ * Draft Mode for its CMS's own preview sent every one of those requests into
+ * Avocado's preview route.
+ */
+test("draftCookie: false leaves Next's draft cookie to whoever else is using it", () => {
+    const { proxy } = createEditorProxy({ draftCookie: false });
+    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");
+});

package/dist/publish/field-diff.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Publishing an edited page back to a CMS, as a field-level diff.
+ *
+ * `onPublish(pages, config)` means "here are the full PageDocs, store them".
+ * That is implementable when the CMS shape *is* the editor shape — a JSON file
+ * — and not otherwise. Every real CMS read is a projection: an asset reference
+ * flattened to a URL string, a document reference resolved to an href for one
+ * language, a rich-text tree flattened to markdown. Writing the projection back
+ * replaces the reference with the flattening and destroys the document.
+ *
+ * So a real integration publishes a diff: walk the same field specs used to
+ * project, compare each field against the value it was projected from, and emit
+ * a set at the key-addressed path that owns it. The first integration to do
+ * this hand-wrote about 230 lines of it. This is that shape, generalised, so
+ * the next one does not.
+ *
+ * **What is here and what is not.** The mechanism is general: the walk, the
+ * unchanged-field skip, list items matched on a stable key rather than an
+ * index, routing a block's patches to a document other than the page's, and the
+ * vocabulary for reporting a change that cannot be expressed. The *inversions*
+ * are not, and cannot be — `rehydrate` undoes a projection only the integration
+ * knows it made. Neither is uploading an asset or re-resolving a reference;
+ * those are per-CMS capabilities, and until an integration has them the honest
+ * answer is `unsupported`, which is why that is a first-class result here
+ * rather than a thrown error.
+ */
+/** How a CMS addresses one element of a list. */
+export interface PathSyntax {
+    /** `prefix` + field, e.g. `pageBuilder[_key=="b1"].heading`. */
+    field(prefix: string, field: string): string;
+    /** The prefix for one item of a list, given its key and position. */
+    item(prefix: string, field: string, key: string, index: number): string;
+}
+/**
+ * Sanity addresses array elements by `_key`, never by index — an index-addressed
+ * patch races any concurrent edit that reorders the array.
+ */
+export declare const sanityPaths: PathSyntax;
+/**
+ * Index addressing, for stores that have no element identity (Strapi component
+ * lists, a plain JSON array). Correct only when the publish is the only writer:
+ * anything that reorders between read and write silently patches the wrong row,
+ * which is exactly what `_key` exists to prevent.
+ */
+export declare const indexPaths: PathSyntax;
+/** One `set` to apply, addressed at the field that owns the value. */
+export interface FieldPatch {
+    documentId: string;
+    path: string;
+    value: unknown;
+}
+/**
+ * A change the editor made that this integration cannot express.
+ *
+ * Reported rather than guessed at. A publisher that silently drops these
+ * reports success for an edit the site will never show; one that guesses writes
+ * a URL where a reference belongs. Both are worse than saying so.
+ */
+export interface UnsupportedChange {
+    /** In the editor's own terms — the page and block a person would recognise. */
+    where: string;
+    /** What was done. */
+    change: string;
+    /** What would have to exist for it to work, when that is known. */
+    remedy?: string;
+}
+export interface FieldDiff {
+    patches: FieldPatch[];
+    unsupported: UnsupportedChange[];
+}
+/**
+ * Emits patches for one changed field, or reports why it cannot.
+ *
+ * This is where a lossy projection is caught. `writeFigure` in the reference
+ * integration sets `alt` — which round-trips — and reports the image itself,
+ * because Sanity stores an asset reference and the editor hands back a URL.
+ */
+export type FieldWriter<Ctx> = (change: {
+    before: unknown;
+    after: unknown;
+    /** The fully-addressed path of this field. */
+    path: string;
+    where: string;
+    ctx: Ctx;
+    emit: (path: string, value: unknown) => void;
+    reject: (change: string, remedy?: string) => void;
+}) => void;
+export interface PublishFieldSpec<Ctx = unknown> {
+    /** The CMS field name, when it differs from the props key. */
+    cmsKey?: string;
+    /**
+     * Undo the projection: given the edited props and the value the CMS holds,
+     * return what the CMS should hold now.
+     *
+     * `before` is passed so an inversion can be partial — return the stored
+     * object with one key replaced, and everything the projection dropped
+     * survives untouched. That is the difference between editing a field and
+     * overwriting a document.
+     */
+    rehydrate(props: Record<string, unknown>, before: unknown, ctx: Ctx): unknown;
+    /** `"set"` writes the value at its path. A function decides for itself. */
+    write?: "set" | FieldWriter<Ctx>;
+    /** For a list field: the specs for one item. */
+    itemFields?: Record<string, PublishFieldSpec<Ctx>>;
+    /** How an item identifies itself upstream. Defaults to reading `_key`. */
+    itemKey?(item: Record<string, unknown>): string | undefined;
+}
+export type FieldSpecs<Ctx> = Record<string, PublishFieldSpec<Ctx>>;
+/** Structural equality, for "did this field actually change". */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/**
+ * Diff one object's fields against the source it was projected from.
+ *
+ * `props` is what the editor holds; `source` is what the CMS holds. Recurses
+ * into list fields, matching items on their own key so a reorder upstream
+ * cannot make a patch land on the wrong row.
+ */
+export declare function diffFields<Ctx>(args: {
+    specs: FieldSpecs<Ctx>;
+    props: Record<string, unknown>;
+    source: Record<string, unknown>;
+    ctx: Ctx;
+    documentId: string;
+    /** Path prefix this object sits at, e.g. `pageBuilder[_key=="b1"].`. */
+    prefix?: string;
+    where: string;
+    paths?: PathSyntax;
+}): FieldDiff;
+/**
+ * Fold a flat patch list into one `set` object per document.
+ *
+ * Most CMS clients take a single patch per document rather than one per field,
+ * and a caller that concatenates diffs from several blocks will have several
+ * entries for the same document. Documents with nothing to set are dropped, so
+ * an unchanged page issues no write at all.
+ */
+export declare function groupPatches(patches: FieldPatch[]): Array<{
+    documentId: string;
+    set: Record<string, unknown>;
+}>;
+/** Merge diffs from several blocks or pages into one. */
+export declare function mergeDiffs(diffs: FieldDiff[]): FieldDiff;
+/** Where one block's values live upstream, and how to invert them. */
+export interface BlockTarget<Ctx> {
+    /** The CMS document that owns these values — not necessarily the page's. */
+    documentId: string;
+    /** Path prefix within that document, e.g. `pageBuilder[_key=="b1"].`. */
+    prefix: string;
+    specs: FieldSpecs<Ctx>;
+    /** What the CMS holds for this block: the value the props were projected from. */
+    source: Record<string, unknown>;
+}
+/**
+ * Diff every block on a page.
+ *
+ * The routing decision stays with the integration — `locate` is where a block
+ * placed by a shared section writes to the *section* document rather than the
+ * page, and where a per-placement heading override stays page-local. Only the
+ * integration knows its own document graph. What is owned here is the loop, the
+ * report for a block with nowhere to write, and the `where` string a person has
+ * to be able to recognise.
+ *
+ * Returning `null` from `locate` reports the block as unpublishable rather than
+ * skipping it silently. That is almost always a block the editor added: the CMS
+ * has no document behind it, so there is no path to patch, and a publisher that
+ * quietly dropped it would report success for content the site will never show.
+ */
+export declare function diffPage<Ctx>(args: {
+    page: {
+        slug: string;
+        blocks: Array<{
+            id: string;
+            type: string;
+            props: Record<string, unknown>;
+        }>;
+    };
+    ctx: Ctx;
+    locate(block: {
+        id: string;
+        type: string;
+        props: Record<string, unknown>;
+    }): BlockTarget<Ctx> | BlockTarget<Ctx>[] | null;
+    paths?: PathSyntax;
+    /** How a block is named in a report. Defaults to `"/slug → type"`. */
+    where?(pageSlug: string, block: {
+        id: string;
+        type: string;
+    }): string;
+}): FieldDiff;
+/** One line per refusal, in the editor's terms. For surfacing to a person. */
+export declare function describeUnsupported(unsupported: UnsupportedChange[]): string[];