@avocadostudio-ai/site-sdk 0.8.0 → 0.10.0

package/README.md

@@ -604,7 +604,7 @@ createOrchestrator({
 `draftPath` is either a prefix the page slug is appended to (`/avocado` →
 `/avocado/de/events`) or a template naming where the slug goes
 (`/preview/{slug}/draft`). It defaults to `/preview-draft`, which is what
-`create-ai-site-editor` scaffolds — **if you wired Avocado into a site you
+`create-avocado-site` scaffolds — **if you wired Avocado into a site you
 already had, set this**, or every draft screenshot comes back a cheerful 200 and
 a picture of your 404 page.
 

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/site-sdk",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -66,6 +66,11 @@
       "import": "./dist/draft-context-core.js",
       "default": "./dist/draft-context-core.js"
     },
+    "./draft/fetch": {
+      "types": "./dist/draft-fetch.d.ts",
+      "import": "./dist/draft-fetch.js",
+      "default": "./dist/draft-fetch.js"
+    },
     "./routes/core": {
       "types": "./dist/routes-core.d.ts",
       "import": "./dist/routes-core.js",
@@ -142,17 +147,17 @@
   ],
   "dependencies": {
     "zod": "^4.3.6",
-    "@avocadostudio-ai/blocks": "^0.8.0",
-    "@avocadostudio-ai/preview-adapter": "^0.8.0",
-    "@avocadostudio-ai/richtext": "^0.8.0",
-    "@avocadostudio-ai/shared": "^0.8.0"
+    "@avocadostudio-ai/preview-adapter": "^0.10.0",
+    "@avocadostudio-ai/blocks": "^0.10.0",
+    "@avocadostudio-ai/richtext": "^0.10.0",
+    "@avocadostudio-ai/shared": "^0.10.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.8.0"
+    "@avocadostudio-ai/orchestrator-core": "^0.10.0"
   },
   "peerDependenciesMeta": {
     "@avocadostudio-ai/orchestrator-core": {