@avocadostudio-ai/site-sdk 0.9.0 → 0.11.0

package/dist/create-site-page.d.ts

@@ -72,6 +72,20 @@ export type SitePageConfig = {
      * config fetch to decorate one Open Graph field.
      */
     siteName?: string;
+    /**
+     * The site's public origin, e.g. `https://example.com`.
+     *
+     * Supplying it turns on the three tags a page cannot derive from its own
+     * content, because none of them is knowable without knowing where the site
+     * lives: `<link rel="canonical">`, `og:url`, and an `og:image` resolved to an
+     * absolute URL. Without it the SDK emits none of them rather than guessing —
+     * a wrong canonical is worse than an absent one.
+     *
+     * Reading it from an environment variable at the call site is the intended
+     * shape (`process.env.NEXT_PUBLIC_SITE_URL`), so preview deployments
+     * self-describe instead of all claiming to be production.
+     */
+    siteUrl?: string;
     /**
      * Last word on a page's metadata. Receives what the SDK derived and the page
      * it derived it from (`null` when the slug has no page), and returns what to

package/dist/create-site-page.js

@@ -19,9 +19,22 @@ function resolve(config) {
         footer: config.footer,
         chrome: config.chrome ?? true,
         siteName: config.siteName,
+        // Trailing slash stripped once, here, so `${siteUrl}${slug}` is well-formed
+        // at every call site rather than producing `https://x.com//about`.
+        siteUrl: config.siteUrl?.trim().replace(/\/+$/, "") || undefined,
         metadata: config.metadata,
     };
 }
+/**
+ * The absolute URL of one page, or undefined when the site has not said where
+ * it lives. `buildSlug` yields "/" for the index and "/a/b" otherwise, so a
+ * plain concatenation is already correct.
+ */
+function canonicalFor(c, slug) {
+    if (!c.siteUrl)
+        return undefined;
+    return slug === "/" ? `${c.siteUrl}/` : `${c.siteUrl}${slug}`;
+}
 function makeGenerateStaticParams(cmsGetSlugs) {
     return async function generateStaticParams() {
         const slugs = await cmsGetSlugs();
@@ -84,7 +97,11 @@ function makeGenerateMetadata(c, mode) {
         const page = await c.cmsGetPage(slug);
         if (!page)
             return decorate({}, null);
-        return decorate(buildPageMetadata(page, { siteName: c.siteName }), page);
+        return decorate(buildPageMetadata(page, {
+            siteName: c.siteName,
+            canonical: canonicalFor(c, slug),
+            baseUrl: c.siteUrl,
+        }), page);
     };
 }
 async function render(slug, search, c, mode) {

package/dist/draft-context-core.js

@@ -1,6 +1,34 @@
 import { validateDraftSecret } from "@avocadostudio-ai/shared";
 import { DRAFT_SESSION_COOKIE, DRAFT_SITE_COOKIE, EDITOR_ORIGIN_COOKIE, normalizeOrigin, resolveTrustedEditorOrigin, single } from "./draft-common.js";
 export { single } from "./draft-common.js";
+/**
+ * Query keys that mean "this request came from the editor".
+ *
+ * `siteId` and `session` are what the editor puts on the iframe URL and what
+ * `editorQuery` re-appends to every link the preview renders, so in-preview
+ * navigation keeps them. `__editor` is the routing hint the middleware and
+ * proxy add. `editorOrigin` names the frame to talk back to, which only the
+ * editor has a reason to send.
+ */
+const EDITOR_QUERY_KEYS = ["siteId", "session", "editorOrigin", "__editor"];
+/**
+ * True when the request carries some evidence that the editor sent it.
+ *
+ * Deliberately not "is the content store enabled" — see the call site. Draft
+ * mode is authoritative on its own: it is only ever turned on by the
+ * secret-gated `/api/draft` handler, which sets the two cookies below in the
+ * same response, so they are a signal in their own right for the rare case a
+ * host reports draft mode differently.
+ */
+function hasEditorIntent(searchParams, adapter, hasValidSecret) {
+    if (adapter.isDraftMode || hasValidSecret)
+        return true;
+    for (const key of EDITOR_QUERY_KEYS) {
+        if (single(searchParams[key])?.trim())
+            return true;
+    }
+    return Boolean(adapter.getCookie(DRAFT_SESSION_COOKIE)?.trim() || adapter.getCookie(DRAFT_SITE_COOKIE)?.trim());
+}
 export async function resolveDraftContextCore(searchParams, adapter, options) {
     const isDev = process.env.NODE_ENV !== "production";
     /*
@@ -30,6 +58,34 @@ export async function resolveDraftContextCore(searchParams, adapter, options) {
     const isContentStoreEnabled = isDev || adapter.isDraftMode || hasValidSecret;
     if (!isContentStoreEnabled)
         return null;
+    /*
+     * Whether this request *may* see drafts and whether it is *asking* to are two
+     * questions, and until now only the first was asked.
+     *
+     * The `isDev` term above answers "may", and in development it is
+     * unconditional. So in dev the only remaining requirement was a siteId — and
+     * the fallback chain below resolves one from `defaultSiteId`, which every
+     * integration configures because it is the site's own identity. Every
+     * anonymous `curl localhost:3000/` therefore came back with a context, and
+     * the caller read that as "this is the editor".
+     *
+     * The consequences were entirely invisible in dev, which is where they
+     * happened: `generateMetadata` short-circuits to noindex-only for an editor
+     * render, so no page in development emitted a title, a description, or an
+     * Open Graph tag; and the render took the draft path, where an unknown slug
+     * is "draft unavailable" at HTTP 200 rather than `notFound()`. A clean-room
+     * reviewer found their titles, social cards, and 404 all unobservable in the
+     * only mode they were running.
+     *
+     * So the request has to say so. Every real editor entry point already does:
+     * the iframe URL carries `?siteId=&session=`, the middleware and proxy add
+     * `__editor=1`, `/api/draft` sets draft mode and the cookies, and a
+     * cross-origin preview carries `secret`. Nothing that reaches the site
+     * without one of those is the editor, and in production nothing changes at
+     * all — every way of passing the gate above is itself a signal.
+     */
+    if (!hasEditorIntent(searchParams, adapter, hasValidSecret))
+        return null;
     const defaultSession = options?.defaultSession ?? process.env.DRAFT_DEFAULT_SESSION?.trim() ?? "dev";
     const defaultSiteId = options?.defaultSiteId ?? process.env.DRAFT_DEFAULT_SITE_ID?.trim() ?? "";
     const defaultEditorOrigin = options?.defaultEditorOrigin

package/dist/editor-routes.d.ts

@@ -27,6 +27,24 @@ export declare function createPagesHandler(getPages: () => PageDoc[] | Promise<P
     GET: (request: Request) => Promise<Response>;
     OPTIONS: (request: Request) => Response;
 };
+/**
+ * Why an unconfigured publish endpoint is refused in production rather than
+ * left open.
+ *
+ * `publishSecret` was optional, and every scaffold and example wired it as
+ * `process.env.PUBLISH_TOKEN?.trim() || undefined` — a variable none of them
+ * generated, mentioned in their `.env.local`, or required. So the value was
+ * always `undefined`, `if (secret)` was always false, and `POST
+ * /api/editor/publish` accepted any caller's `pages` array and overwrote the
+ * site's content with it. A deployment that had followed its own README to the
+ * letter, `ACCESS_PASSWORD_HASH` and all, was gated on `/api/avocado/*` and
+ * wide open here: the two route groups are different handlers, and only one of
+ * them had ever been asked about auth.
+ *
+ * An optional guard on a write endpoint is not a guard. This one now fails
+ * closed wherever it matters and says which variable opens it.
+ */
+export declare const OPEN_PUBLISH_HINT: string;
 export declare function createPublishHandler(onPublish: OnPublishFn, options?: {
     publishSecret?: string;
 }): {

package/dist/editor-routes.js

@@ -29,12 +29,45 @@ export function createPagesHandler(getPages, getSiteConfig) {
         }
     };
 }
+/**
+ * Why an unconfigured publish endpoint is refused in production rather than
+ * left open.
+ *
+ * `publishSecret` was optional, and every scaffold and example wired it as
+ * `process.env.PUBLISH_TOKEN?.trim() || undefined` — a variable none of them
+ * generated, mentioned in their `.env.local`, or required. So the value was
+ * always `undefined`, `if (secret)` was always false, and `POST
+ * /api/editor/publish` accepted any caller's `pages` array and overwrote the
+ * site's content with it. A deployment that had followed its own README to the
+ * letter, `ACCESS_PASSWORD_HASH` and all, was gated on `/api/avocado/*` and
+ * wide open here: the two route groups are different handlers, and only one of
+ * them had ever been asked about auth.
+ *
+ * An optional guard on a write endpoint is not a guard. This one now fails
+ * closed wherever it matters and says which variable opens it.
+ */
+export const OPEN_PUBLISH_HINT = "This publish endpoint overwrites the site's content and has no publishSecret configured, " +
+    "so it refuses every request under NODE_ENV=production. Set PUBLISH_TOKEN (the same value the " +
+    "orchestrator sends as x-publish-token), or pass publishSecret to createEditorApiHandler().";
+let warnedOpenPublish = false;
 export function createPublishHandler(onPublish, options) {
     return {
         OPTIONS: createEditorCorsOptionsHandler(),
         async POST(request) {
             // Verify publish token if configured
             const secret = options?.publishSecret;
+            if (!secret) {
+                if (process.env.NODE_ENV === "production") {
+                    const res = new Response(JSON.stringify({ ok: false, error: "unauthorized", reason: OPEN_PUBLISH_HINT }), { status: 401, headers: { "Content-Type": "application/json" } });
+                    return applyEditorCors(res, request.headers.get("origin"));
+                }
+                // Development: publishing to your own machine is the point, so this
+                // stays open — but it is the same code path that ships, so say so once.
+                if (!warnedOpenPublish) {
+                    warnedOpenPublish = true;
+                    console.warn(`[avocado] ${OPEN_PUBLISH_HINT}`);
+                }
+            }
             if (secret) {
                 const provided = request.headers.get("x-publish-token")?.trim();
                 if (!provided || provided !== secret) {

package/dist/page-metadata.d.ts

@@ -55,7 +55,28 @@ export type BuildPageMetadataOptions = {
     siteName?: string;
     /** Absolute URL of this page, used for the canonical link and `og:url`. */
     canonical?: string;
+    /**
+     * The site's own origin, used to turn a relative `ogImage` into the absolute
+     * URL a crawler can actually fetch.
+     *
+     * Content stores relative paths because that is what the page renders from —
+     * `/generated-images/hero.webp` is correct in an `<img src>` and useless in
+     * an `og:image`, where Facebook, Slack, and X all decline to resolve it
+     * against the page. The demo shipped eight pages whose images are exactly
+     * that shape, so its social cards were blank while every check passed: the
+     * build gate asserts "has og:image exactly when the page declares one", and
+     * declaring an unusable one satisfies it.
+     */
+    baseUrl?: string;
 };
+/**
+ * Resolve an image reference against the site's origin.
+ *
+ * Returns the input unchanged when there is nothing to resolve against, which
+ * keeps the no-`baseUrl` behaviour exactly as it was: a relative path still
+ * goes out relative rather than becoming a broken absolute one.
+ */
+export declare function absolutizeImage(image: string, baseUrl: string | undefined): string;
 /**
  * Build the full metadata object for a page.
  *

package/dist/page-metadata.js

@@ -77,6 +77,27 @@ export function derivePageDescription(page) {
 export function derivePageTitle(page) {
     return page.meta?.title?.trim() || page.title;
 }
+/** Absolute already, a protocol-relative URL, or a data URI — leave it alone. */
+function isAbsoluteUrl(value) {
+    return /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(value);
+}
+/**
+ * Resolve an image reference against the site's origin.
+ *
+ * Returns the input unchanged when there is nothing to resolve against, which
+ * keeps the no-`baseUrl` behaviour exactly as it was: a relative path still
+ * goes out relative rather than becoming a broken absolute one.
+ */
+export function absolutizeImage(image, baseUrl) {
+    if (!baseUrl || isAbsoluteUrl(image))
+        return image;
+    try {
+        return new URL(image, baseUrl).toString();
+    }
+    catch {
+        return image;
+    }
+}
 /**
  * Build the full metadata object for a page.
  *
@@ -87,7 +108,8 @@ export function derivePageTitle(page) {
 export function buildPageMetadata(page, options = {}) {
     const title = derivePageTitle(page);
     const description = derivePageDescription(page);
-    const image = page.meta?.ogImage?.trim();
+    const rawImage = page.meta?.ogImage?.trim();
+    const image = rawImage ? absolutizeImage(rawImage, options.baseUrl) : undefined;
     const images = image ? [image] : undefined;
     return {
         title,

package/dist/publish-handlers/json-file.d.ts

@@ -2,6 +2,21 @@ import type { OnPublishFn } from "../editor-routes.ts";
 /**
  * Publish handler that writes PageDoc[] to a local JSON file.
  *
+ * `shape` decides what lands in the file, and it has to match whatever reads
+ * it back. It used to be neither a parameter nor a choice: the handler always
+ * wrote `{ pages, siteConfig }` while this docstring, three of the four call
+ * sites, and `jsonFileAdapter.onPublish` all said `PageDoc[]`. Publishing then
+ * broke the site that had just published — the scaffold's `lib/content.ts`
+ * does `JSON.parse(...) as PageDoc[]` and its `.find` threw on an object, so
+ * every page answered 500, and `examples/sample-site` reads a slug-keyed
+ * object and quietly lost all nine pages. Only `apps/site` survived, because
+ * its reader had already grown a branch for both shapes.
+ *
+ * So: `array` is the default, because it is what the readers and the adapter
+ * expect. Pass `wrapper` when the reader wants `siteConfig` in the same file —
+ * a plain array has nowhere to put it, so site-level settings (name, logo,
+ * nav) are dropped on publish.
+ *
  * When `publicDir` is provided, inline assets (base64 images from the
  * orchestrator) are written to disk and their localhost URLs are rewritten
  * to relative paths in the JSON output.
@@ -21,4 +36,6 @@ import type { OnPublishFn } from "../editor-routes.ts";
 export declare function createJsonFilePublishHandler(filePath: string, options?: {
     publicDir?: string;
     imagePathPrefix?: string;
+    /** `array` writes `PageDoc[]` (default). `wrapper` writes `{ pages, siteConfig }`. */
+    shape?: "array" | "wrapper";
 }): OnPublishFn;

package/dist/publish-handlers/json-file.js

@@ -3,6 +3,21 @@ import { resolve } from "node:path";
 /**
  * Publish handler that writes PageDoc[] to a local JSON file.
  *
+ * `shape` decides what lands in the file, and it has to match whatever reads
+ * it back. It used to be neither a parameter nor a choice: the handler always
+ * wrote `{ pages, siteConfig }` while this docstring, three of the four call
+ * sites, and `jsonFileAdapter.onPublish` all said `PageDoc[]`. Publishing then
+ * broke the site that had just published — the scaffold's `lib/content.ts`
+ * does `JSON.parse(...) as PageDoc[]` and its `.find` threw on an object, so
+ * every page answered 500, and `examples/sample-site` reads a slug-keyed
+ * object and quietly lost all nine pages. Only `apps/site` survived, because
+ * its reader had already grown a branch for both shapes.
+ *
+ * So: `array` is the default, because it is what the readers and the adapter
+ * expect. Pass `wrapper` when the reader wants `siteConfig` in the same file —
+ * a plain array has nowhere to put it, so site-level settings (name, logo,
+ * nav) are dropped on publish.
+ *
  * When `publicDir` is provided, inline assets (base64 images from the
  * orchestrator) are written to disk and their localhost URLs are rewritten
  * to relative paths in the JSON output.
@@ -33,8 +48,8 @@ export function createJsonFilePublishHandler(filePath, options) {
             }
             output = JSON.parse(json);
         }
-        const payload = JSON.stringify({ pages: output, siteConfig: config }, null, 2) + "\n";
-        await writeFile(filePath, payload, "utf8");
+        const body = options?.shape === "wrapper" ? { pages: output, siteConfig: config } : output;
+        await writeFile(filePath, JSON.stringify(body, null, 2) + "\n", "utf8");
         return { ok: true };
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/site-sdk",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -147,17 +147,17 @@
   ],
   "dependencies": {
     "zod": "^4.3.6",
-    "@avocadostudio-ai/blocks": "^0.9.0",
-    "@avocadostudio-ai/preview-adapter": "^0.9.0",
-    "@avocadostudio-ai/richtext": "^0.9.0",
-    "@avocadostudio-ai/shared": "^0.9.0"
+    "@avocadostudio-ai/preview-adapter": "^0.11.0",
+    "@avocadostudio-ai/shared": "^0.11.0",
+    "@avocadostudio-ai/richtext": "^0.11.0",
+    "@avocadostudio-ai/blocks": "^0.11.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.9.0"
+    "@avocadostudio-ai/orchestrator-core": "^0.11.0"
   },
   "peerDependenciesMeta": {
     "@avocadostudio-ai/orchestrator-core": {