@bettercms-ai/astro 0.13.0 → 0.14.0

package/README.md

@@ -29,12 +29,28 @@ export default defineConfig({
 });
 ```
 
-Server env (never bundled to the client):
+### Environment variables
 
-```bash
-BCMS_API_KEY=bcms_proj_...      # content:read (or content:read:draft for previews)
-BCMS_DRAFT_SECRET=<32+ chars>   # signs the draft cookie
-```
+Every public value resolves in this order: `bettercms({ ... })` option, then env, then the
+`bcms-content.json` snapshot the deploy workflow writes before the build.
+
+| Variable | Option | Read | Default / notes |
+| --- | --- | --- | --- |
+| `PUBLIC_BCMS_API_URL` | `apiUrl` | config time | Required (option, env or snapshot) |
+| `PUBLIC_BCMS_WORKSPACE` | `workspace` | config time | Required (option, env or snapshot) |
+| `PUBLIC_BCMS_PROJECT_ID` | `projectId` | config time | Optional project scope for forms |
+| `PUBLIC_BCMS_MEDIA_URL` | `mediaUrl` | config time | `https://cdn.bettercms.ai` |
+| `PUBLIC_BCMS_STUDIO_URL` | `studioUrl` | config time | Unset. `<BcmsVisualEditing>` falls back to `https://bettercms.ai` |
+| `BCMS_API_KEY` | none | server runtime | `content:read`, or `content:read:draft` for draft previews. Never bundled |
+| `BCMS_DRAFT_SECRET` | none | server runtime | Signs the draft cookie. Runtime `process.env` wins over a build-time value. Without it `/api/bcms/draft/enable` returns 500 |
+
+The BetterCMS-generated deploy workflow sets `PUBLIC_BCMS_API_URL`, `PUBLIC_BCMS_WORKSPACE`
+and `PUBLIC_BCMS_PROJECT_ID` for the build. Its repo secret `BCMS_API_KEY` reaches only the
+content-fetch step, never the build. On your own host, set the two server variables yourself.
+
+This package ships no revalidation route. Point the project's revalidation webhook
+(Project → Settings) at your rebuild hook. Its secret (the dashboard calls it
+`BETTERCMS_WEBHOOK_SECRET`) signs the body as `x-bettercms-signature: sha256=<hmac>`.
 
 Add the virtual-module + `Astro.locals` types to `src/env.d.ts`:
 
@@ -170,3 +186,23 @@ The integration injects `/api/bcms/draft/enable?token=<jwt>&redirect=/path` and
 `/api/bcms/draft/disable`. Generate the preview-token link from the dashboard;
 visiting `enable` validates the token against the backend, sets a signed cookie,
 and subsequent loads return draft content. Disable with the `disable` route.
+
+### Two draft lanes
+
+| Lane | Build | How the canvas shows a draft |
+| --- | --- | --- |
+| SSR | `output: "server"` + the draft routes above + `BCMS_DRAFT_SECRET` + a `content:read:draft` `BCMS_API_KEY` | The loaders read the draft on every request, so hand-written layouts preview too |
+| Static | Any static build, with the page body rendered through `<BcmsLiveBlocks>` | The editor pushes the draft block tree to the island over `postMessage`. No fetch, no key in the page. Only the `BcmsLiveBlocks` region updates |
+
+## Headless projects (your own host)
+
+BetterCMS never builds, releases or deploys a headless project. Any build, artifact or deploy
+request for one returns **409 `HEADLESS_NO_BUILD`**.
+
+- **Deploy:** push to your repository. Your provider (Vercel, Netlify or Cloudflare Pages)
+  builds it. For fresh content on publish, point the revalidation webhook at the provider's
+  rebuild hook.
+- **Draft:** use your framework's draft route on the provider's **preview** deployment URL.
+  For Astro that is the SSR lane above: `output: "server"`, the injected
+  `/api/bcms/draft/*` routes, `BCMS_DRAFT_SECRET`, and a `BCMS_API_KEY` carrying
+  `content:read:draft`. Keep the draft key off production.

package/components/BcmsVisualEditing.astro

@@ -16,11 +16,10 @@
 interface Props {
   studioUrl?: string;
 }
-// `demo.bettercms.ai` is the studio origin — the same one the dashboard's own integration
-// snippets hand out as `PUBLIC_BCMS_STUDIO_URL`. `dashboard.bettercms.ai` resolves but 404s;
-// it is the straggler `public-lookup.ts` already called "the odd one out among three
-// spellings of this origin", and it was left here.
-const { studioUrl = "https://demo.bettercms.ai" } = Astro.props;
+// `bettercms.ai` is the studio origin — the one the dashboard's integration snippets hand out
+// as `PUBLIC_BCMS_STUDIO_URL`, and the default of @bettercms-ai/next's <VisualEditing>.
+// `demo.bettercms.ai` is a stale alias; `dashboard.bettercms.ai` resolves but 404s.
+const { studioUrl = "https://bettercms.ai" } = Astro.props;
 const src = `${studioUrl.replace(/\/+$/, "")}/bcms-visual-editing.js`;
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bettercms-ai/astro",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "description": "The BetterCMS adapter for Astro — a `bettercms()` integration, a `bettercms:client` virtual module, typed content loaders, draft preview, and native .astro rendering components.",
   "main": "./dist/index.js",
@@ -54,11 +54,11 @@
   },
   "dependencies": {
     "@bettercms-ai/image-url": "^0.3.0",
-    "@bettercms-ai/sdk": "^1.18.0",
+    "@bettercms-ai/sdk": "^1.20.0",
     "@bettercms-ai/types": "^1.11.0",
     "@bettercms-ai/ui": "^0.7.0",
     "@bettercms-ai/richtext": "^0.3.0",
-    "@bettercms-ai/next": "^0.12.1"
+    "@bettercms-ai/next": "^0.13.0"
   },
   "peerDependencies": {
     "astro": ">=4",