@avocadostudio-ai/site-sdk 0.1.0

package/dist/revalidate-handler.js

@@ -0,0 +1,77 @@
+/**
+ * Factory for CMS webhook → ISR revalidation + orchestrator bootstrap routes.
+ *
+ * All three CMS integrations follow the same pattern:
+ * 1. Validate webhook secret
+ * 2. Extract slug from CMS-specific body shape
+ * 3. Call Next.js revalidatePath()
+ * 4. Re-bootstrap orchestrator with fresh content
+ *
+ * This factory extracts that into a single configurable handler.
+ *
+ * Usage:
+ * ```ts
+ * export const POST = createRevalidateHandler({
+ *   secretEnvVar: "SANITY_WEBHOOK_SECRET",
+ *   extractSlug: (body) => (body as any)?.slug?.current ?? null,
+ *   getPages: getSanityPages,
+ *   siteId: "sanity-site",
+ * })
+ * ```
+ */
+export function createRevalidateHandler(config) {
+    const { secretEnvVar, extractSlug, getPages, siteId, session = "dev" } = config;
+    const secretHeader = config.secretHeader === undefined ? "x-revalidate-secret" : config.secretHeader;
+    return async function POST(request) {
+        const configuredSecret = process.env[secretEnvVar]?.trim();
+        if (!configuredSecret) {
+            return Response.json({ error: `${secretEnvVar} not configured` }, { status: 500 });
+        }
+        // Validate secret: check configured sources in order
+        let provided;
+        const sources = secretHeader === null ? ["query:secret"]
+            : Array.isArray(secretHeader) ? secretHeader
+                : [secretHeader];
+        const url = new URL(request.url);
+        for (const src of sources) {
+            if (src.startsWith("query:")) {
+                provided = url.searchParams.get(src.slice(6))?.trim() ?? undefined;
+            }
+            else {
+                provided = request.headers.get(src)?.trim() ?? undefined;
+            }
+            if (provided)
+                break;
+        }
+        if (!provided || provided !== configuredSecret) {
+            return Response.json({ error: "Invalid secret" }, { status: 401 });
+        }
+        try {
+            const body = await request.json();
+            const rawSlug = extractSlug(body) ?? "/";
+            const path = rawSlug === "/" ? "/" : `/${rawSlug.replace(/^\//, "")}`;
+            // ISR revalidation — dynamic import to avoid hard dep on next
+            try {
+                const { revalidatePath } = await import(/* webpackIgnore: true */ "next/cache");
+                revalidatePath(path);
+            }
+            catch {
+                // Not running in Next.js or revalidatePath unavailable
+            }
+            // Re-bootstrap orchestrator with fresh CMS content
+            const orchestratorUrl = process.env.ORCHESTRATOR_URL;
+            if (orchestratorUrl) {
+                const pages = await getPages();
+                await fetch(`${orchestratorUrl}/draft/bootstrap`, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ session, siteId, pages, overwrite: true }),
+                }).catch(() => { });
+            }
+            return Response.json({ revalidated: true, path });
+        }
+        catch {
+            return Response.json({ error: "Invalid request body" }, { status: 400 });
+        }
+    };
+}

package/dist/routes.d.ts

@@ -0,0 +1,10 @@
+export { createDraftEnableHandler, createDraftDisableHandler } from "./draft-routes.ts";
+export { createBlocksHandler, createPagesHandler, createPublishHandler } from "./editor-routes.ts";
+export type { OnPublishFn, InlineAsset, PublishContext } from "./editor-routes.ts";
+export { createEditorApiHandler } from "./editor-api-handler.ts";
+export type { EditorApiHandlerConfig } from "./editor-api-handler.ts";
+export { isSafeImageUrl, createImageResolver } from "./publish-utils.ts";
+export type { ImageUploader } from "./publish-utils.ts";
+export { createRevalidateHandler } from "./revalidate-handler.ts";
+export type { RevalidateHandlerConfig } from "./revalidate-handler.ts";
+export { getManifestImageFields } from "./manifest-utils.ts";

package/dist/routes.js

@@ -0,0 +1,12 @@
+// Draft route handler factories
+export { createDraftEnableHandler, createDraftDisableHandler } from "./draft-routes.js";
+// Editor route handler factories
+export { createBlocksHandler, createPagesHandler, createPublishHandler } from "./editor-routes.js";
+// Catch-all editor API handler
+export { createEditorApiHandler } from "./editor-api-handler.js";
+// Publish utilities (SSRF check, image resolution)
+export { isSafeImageUrl, createImageResolver } from "./publish-utils.js";
+// Revalidation handler factory
+export { createRevalidateHandler } from "./revalidate-handler.js";
+// Manifest utilities (derive image fields from block manifest)
+export { getManifestImageFields } from "./manifest-utils.js";

package/dist/server/orchestrator.d.ts

@@ -0,0 +1,117 @@
+import { type AIProvider, type ModelKey } from "@avocadostudio-ai/orchestrator-core/state/session-state.js";
+import { type Logger } from "@avocadostudio-ai/orchestrator-core/logger.js";
+import type { CmsAdapter } from "@avocadostudio-ai/orchestrator-core/cms/adapter.js";
+export interface CreateOrchestratorConfig {
+    /**
+     * Provider model overrides. Defaults to env vars (OPENAI_MODEL_*, ANTHROPIC_MODEL_*,
+     * GOOGLE_GENAI_MODEL_*). Pass an explicit object to override per-tier model names.
+     */
+    modelLookup?: Record<AIProvider, Record<ModelKey, string>>;
+    /**
+     * Override available providers. Defaults to whichever API keys are present in
+     * process.env (OPENAI_API_KEY / ANTHROPIC_API_KEY / GOOGLE_GENAI_API_KEY).
+     */
+    availableProviders?: AIProvider[];
+    /** Pino-shaped logger. Defaults to a console-backed implementation. */
+    logger?: Logger;
+    /**
+     * Allowed CORS origins. Defaults to "*". For production, pass an explicit
+     * allow-list (Next.js can also handle CORS via middleware — pass null here
+     * to disable the SDK's CORS handling entirely).
+     */
+    corsOrigins?: string[] | "*" | null;
+    /**
+     * Register the default builtin tools (unsplash-search, image-generate,
+     * gdrive-browse). Defaults to `false` — opt in only if you want those
+     * features, since registering them pulls in sharp + googleapis + image-gen
+     * SDKs at module load. Pass `true` for env-gated defaults, or an explicit
+     * subset like `["unsplash-search"]`.
+     */
+    builtinTools?: boolean | Array<"unsplash-search" | "image-generate" | "gdrive-browse">;
+    /**
+     * URL path prefix the handler is mounted under. Everything matching this
+     * prefix is stripped off `url.pathname` before route matching, so the rest
+     * of the handler can reason in terms of `/chat`, `/chat/stream`, etc.
+     *
+     * Defaults to `/api/avocado` (the catch-all path used in the Next.js
+     * example app). Set to `""` if you want to match against the full pathname
+     * yourself, or override to e.g. `/api/orchestrator` if you mount the
+     * catch-all there.
+     */
+    basePath?: string;
+    /**
+     * Source-of-truth adapter for the site's existing content. Called once per
+     * session on the first chat request to seed SQLite with the site's pages.
+     * Without an adapter the orchestrator starts with an empty draft, which
+     * means the planner has no pages to edit — every "edit the homepage" turn
+     * returns `page not found`.
+     *
+     * Provided implementations:
+     *  - `jsonFileAdapter({ path })` — read PageDoc[] from a JSON file
+     *  - `editorApiAdapter({ origin })` — fetch from `${origin}/api/editor/pages`
+     *
+     * Import from `@avocadostudio-ai/orchestrator-core/cms`.
+     */
+    adapter?: CmsAdapter;
+    /**
+     * Site identifier used to scope session state in SQLite. When `adapter` is
+     * set, defaults to `"library"` so the demo-content seed path is bypassed
+     * (an unscoped session falls back to the orchestrator's bundled demo pages).
+     * Override if you want to run multiple distinct sites against one process.
+     *
+     * Precedence on incoming requests:
+     *   - adapter configured: `siteId` (or its `"library"` default) ALWAYS wins
+     *     over `body.siteId`. The library-mode orchestrator owns its identity.
+     *   - no adapter: explicit `siteId` wins; otherwise `body.siteId` is used.
+     */
+    siteId?: string;
+    /**
+     * Register the site's block schemas before the orchestrator's first chat
+     * request. Use this instead of relying on side-effect import order: in
+     * library mode, the orchestrator's transitive imports of
+     * `@avocadostudio-ai/shared` re-register canonical Hero/CTA/etc. on the
+     * shared globalThis registry, often AFTER the host app's overrides.
+     *
+     * **Fires once per orchestrator runtime** — at `buildRuntime` time, not
+     * per-request. For long-lived production processes this is fine, but if
+     * the host re-builds the runtime on hot-reload, ensure the schemas survive
+     * (registerBlock is idempotent — calling again is safe). Pair this with
+     * the same `registerBlocks` passed to `createEditorApiHandler`, which
+     * re-runs on every `/blocks` request, to cover request-time too.
+     */
+    registerBlocks?: () => void;
+    /**
+     * Local directory where `POST /image/upload` writes uploaded files and
+     * `GET /generated-images/:fileName` reads them back. Defaults to
+     * `.data/generated-images` under the host process CWD.
+     *
+     * **POC-grade storage.** Files live on the orchestrator host's local disk
+     * with no CDN, no image transforms, and no durability guarantee — on an
+     * ephemeral filesystem (e.g. a container without a mounted volume) uploads
+     * vanish on redeploy. See `docs/image-storage-options.md` for the path to a
+     * blob/CDN backend; that swap is contained to these two routes.
+     */
+    imageDir?: string;
+}
+/**
+ * A handler returned by {@link createOrchestrator}. Callable like the bare
+ * Web `(Request) => Promise<Response>` it always was, with an extra
+ * `dispose()` method to release the resumable-stream sweep timer (call this
+ * during dev hot-reload or test teardown).
+ */
+export type OrchestratorHandler = ((request: Request) => Promise<Response>) & {
+    dispose(): Promise<void>;
+};
+export type { CmsAdapter, CmsInlineAsset, CmsPublishContext, CmsPublishResult } from "@avocadostudio-ai/orchestrator-core/cms/adapter.js";
+export { jsonFileAdapter, editorApiAdapter } from "@avocadostudio-ai/orchestrator-core/cms/index.js";
+/**
+ * Build a Web-standard request handler that wraps the orchestrator brain.
+ *
+ * Usage in Next.js App Router (`app/api/avocado/[[...path]]/route.ts`):
+ *
+ *     export const runtime = "nodejs"
+ *     const handler = createOrchestrator()
+ *     export const POST = handler
+ *     export const OPTIONS = handler
+ */
+export declare function createOrchestrator(config?: CreateOrchestratorConfig): OrchestratorHandler;