agent-cms 0.1.0 → 0.3.0

package/README.md

@@ -6,7 +6,7 @@ Agent-first headless CMS. Runs as a Cloudflare Worker backed by D1 and R2 in you
 
 - **Structured text with typed blocks** — a document tree where rich components (code blocks, media, custom types) are embedded inline. One GraphQL query returns the full tree with discriminated block unions. Map directly to React/Svelte/Vue components in a single server hop. Render with [`react-datocms`](https://github.com/datocms/react-datocms), `vue-datocms`, or `datocms-svelte` — the structured text format is [DAST](https://www.datocms.com/docs/structured-text/dast), an open standard.
 - **Hybrid search** — FTS5 for keyword matching, Cloudflare Vectorize for semantic similarity, combined with reciprocal rank fusion. All on D1.
-- **Draft/publish with scheduling** — records start as drafts. Publishing captures a version snapshot. Schedule publish/unpublish at future datetimes. Full version history — restore to any snapshot, and the restore itself is reversible.
+- **Draft/publish with preview** — records start as drafts. Publishing captures a version snapshot. Models can declare a `canonicalPathTemplate` so agents and editors get preview URLs for drafts. Short-lived preview tokens grant draft access to GraphQL without editor credentials. Schedule publish/unpublish at future datetimes. Full version history — restore to any snapshot, and the restore itself is reversible.
 - **Geospatial filtering** — `lat_lon` field type with `near(latitude, longitude, radius)` queries in GraphQL.
 - **Automatic reverse references** — link model A to model B, and B gets a query field for all records in A that reference it, with full filtering, ordering, and pagination.
 - **Two MCP servers** — admin MCP (`/mcp`) for schema and content, editor MCP (`/mcp/editor`) scoped to content operations only. Create editor tokens with optional expiry.
@@ -107,6 +107,115 @@ FTS5 keyword search with BM25 ranking and snippets, scoped to all models or a si
 - **`semantic`** — Vectorize cosine similarity.
 - **`hybrid`** (default) — Reciprocal rank fusion of keyword + semantic results.
 
+## Draft preview
+
+Records on draft-enabled models start as drafts. The CMS stores both the draft state (real columns) and the published snapshot. GraphQL serves published content by default. Draft preview lets agents and editors see unpublished content on the real site before publishing.
+
+### How it works
+
+1. **Set a URL template on your model** — `canonicalPathTemplate: "/posts/{slug}"`. The CMS resolves `{slug}` from the record and includes `_previewPath` in tool/REST responses.
+
+2. **Configure the site URL** — pass `siteUrl` to `createCMSHandler`. The CMS uses this to generate fully assembled preview links.
+
+3. **Agent or editor requests a preview** — the `get_preview_url` MCP tool returns a ready-to-share link with a short-lived preview token baked in. One tool call, no assembly required.
+
+4. **User clicks the preview link** — the site's enable route validates the token against the CMS, sets a cookie, and redirects to the content page. The site then fetches draft content from GraphQL.
+
+5. **Disable draft mode** — clear the cookie via `/api/draft-mode/disable?redirect=/`.
+
+### MCP workflow
+
+The agent never assembles preview URLs manually. One tool call does everything:
+
+```
+Agent: create_record({ modelApiKey: "post", data: { title: "Draft Post", ... } })
+CMS:   { id: "abc", _status: "draft", _previewPath: "/posts/draft-post" }
+
+Agent: get_preview_url({ recordId: "abc", modelApiKey: "post" })
+CMS:   { url: "https://mysite.com/api/draft-mode/enable?token=pvt_...&redirect=/posts/draft-post",
+         previewPath: "/posts/draft-post", expiresAt: "2026-03-24T17:00:00Z" }
+
+Agent: "Here's your draft preview: https://mysite.com/api/draft-mode/enable?token=pvt_...&redirect=/posts/draft-post"
+```
+
+If the agent has browser access, it can follow the link to visually verify content and iterate before publishing.
+
+### Site integration
+
+The package exports `createPreviewHandler` for the common case (Astro, SvelteKit, generic Workers). For Next.js, use `draftMode().enable()` in your route handler alongside the CMS cookie — see the framework-specific notes below.
+
+```ts
+import { createPreviewHandler } from "agent-cms";
+
+const preview = createPreviewHandler({
+  cmsBaseUrl: "https://my-cms.workers.dev",
+});
+
+// Mount at /api/draft-mode/* in your site's router
+```
+
+The handler validates the token against the CMS, sets an `HttpOnly` cookie (`__agentcms_preview`) with the token, and redirects. The cookie's `Max-Age` matches the token's remaining TTL.
+
+In your GraphQL client, forward the cookie as a header when present:
+
+```ts
+const previewToken = getCookie("__agentcms_preview");
+const headers: Record<string, string> = {};
+if (previewToken) {
+  headers["X-Preview-Token"] = previewToken;
+  headers["Cache-Control"] = "no-store"; // bypass CDN for draft content
+}
+```
+
+GraphQL responses in preview mode include `Cache-Control: private, no-store` and a `_preview` field:
+
+```graphql
+{ _preview { enabled expiresAt } }
+```
+
+Use this to render a preview banner — or include the `<agent-cms-preview-bar>` web component that shows "Draft Mode" with a disable link.
+
+### Service bindings
+
+When your site and CMS are in the same Cloudflare account, skip cookies entirely. Pass `X-Preview-Token` directly on the service binding call:
+
+```ts
+const res = await env.CMS.fetch("https://internal/graphql", {
+  headers: {
+    "X-Preview-Token": previewToken, // from your site's own session/cookie
+  },
+  body: JSON.stringify({ query }),
+});
+```
+
+No CORS, no cross-origin cookies, zero latency. This is the recommended path for Cloudflare deployments.
+
+### Framework notes
+
+**Astro / SvelteKit / generic Workers** — use `createPreviewHandler` directly. Read the cookie in middleware and forward as `X-Preview-Token`.
+
+**Next.js** — your enable route must also call `draftMode().enable()` to integrate with Next.js ISR/caching. Set `SameSite=None; Secure` on the cookie for iframe compatibility. See the DatoCMS Next.js pattern — the same approach applies.
+
+### URL templates
+
+Templates use `{field_name}` placeholders resolved from the record:
+
+| Template | Record | Result |
+|----------|--------|--------|
+| `/posts/{slug}` | `{ slug: "hello-world" }` | `/posts/hello-world` |
+| `/docs/{category}/{slug}` | `{ category: "guides", slug: "setup" }` | `/docs/guides/setup` |
+| `/{slug}` | `{ slug: "about" }` | `/about` |
+
+Templates are paths only — no origin, no locale prefix. Locale URL strategies (prefix, subdomain, root folding) are handled by your site's routing, not the CMS. The enable route accepts an optional `locale` param for your middleware to use.
+
+### Preview tokens
+
+- Created internally by `get_preview_url` or via `POST /api/preview-tokens`
+- Default expiry: 24 hours (editorial workflows are async)
+- Stored as SHA-256 hashes in D1 (a database breach doesn't leak usable tokens)
+- Grant read-only access to all draft content via GraphQL
+- `X-Preview-Token` header takes precedence over `__agentcms_preview` cookie if both are present
+
 ## Editor tokens
 
 Editor tokens are the credential for non-admin editing flows. Create them via `POST /api/tokens` or the `editor_tokens` MCP tool (with `action: "create"`). The raw token is shown once; the server stores a hash.
@@ -177,6 +286,7 @@ Only `DB` is required. Everything else is optional and degrades gracefully.
 | `VECTORIZE` | Vectorize | Semantic vector search. Requires `AI`. |
 | `CMS_WRITE_KEY` | Secret | Auth for writes, MCP, and publish. Without it, writes are open. |
 | `ASSET_BASE_URL` | Variable | Public URL prefix for assets and Image Resizing. Must be a custom domain for transforms. |
+| `SITE_URL` | Variable | Your site's public URL (e.g. `https://mysite.com`). Required for `get_preview_url` to generate fully assembled preview links. |
 
 ```jsonc
 {
@@ -212,7 +322,8 @@ Focal points, blurhash, and color palette are stored per-asset. Cloudflare Image
 
 ## Examples
 
-- [`examples/blog/`](./examples/blog/) — CMS Worker + Astro SSR site with typed GraphQL (gql.tada), structured text rendering, responsive images, service bindings
+- [`examples/blog/`](./examples/blog/) — CMS Worker + Astro SSR site with typed GraphQL (gql.tada), structured text rendering, responsive images, service bindings, **draft preview mode**
+- [`examples/nextjs/`](./examples/nextjs/) — Next.js App Router with `draftMode()` integration, multi-root GraphQL queries, preview bar component
 - [`examples/editor-mcp/`](./examples/editor-mcp/) — editor onboarding: app-land OAuth gateway, scoped editor tokens, separate MCP URLs for developers and editors
 
 ## License