@mapled/next 0.6.0 → 0.7.1

package/README.md

@@ -4,18 +4,215 @@ Read published [Mapled](https://mapled.io) content in a Next.js site — a deliv
 
 Mapled is a hosted headless CMS built for sites created with AI. Your agent (or you) models collections and fills in content; this package is how the site reads what's published.
 
+- [Install](#install)
+- [Integrate by hand](#integrate-by-hand) — the whole integration step by step, no AI agent needed
+- Reference: [Read published content](#read-published-content) • [Rich text](#rich-text) • [Images](#images) • [Refresh on publish](#refresh-on-publish) • [Preview drafts](#preview-drafts) • [Forms](#forms) • [Live data](#live-data) • [Without Next.js: the HTTP API](#without-nextjs-the-http-api) • [API](#api)
+
 ## Install
 
 ```bash
 npm install @mapled/next
 ```
 
-Grab the delivery key in Mapled: project → Integrations → **Your site**, and put it in your site's env:
+Grab the delivery key in Mapled: project settings (the gear in the project's header) → **Integrations** → **Your site**, and put it in your site's env:
 
 ```bash
 MAPLED_KEY=mk_live_…
 ```
 
+## Integrate by hand
+
+An AI agent connected through [`@mapled/mcp`](https://www.npmjs.com/package/@mapled/mcp) does all of this for you. Nothing in it needs one, though: this is the same integration, step by step — from a Next.js site with hardcoded content to a site its editors run from Mapled. Plan on an hour for a small site.
+
+You need a Mapled project where you can change the structure (the builder plan), a Next.js 14+ site on the App Router, and Node 18 or newer. The example is a site with a homepage and a blog; the keys (`homepage`, `articles`) are whatever you choose in step 1.
+
+### 1. Model the content
+
+In Mapled, open the project and press the wrench in the header (**Structure**) → **Collections**. Create a **single** for every one-off part of the site (`homepage`, `footer`) and a **collection** for every list of alike things (`articles`, `team`), then **Add field** for each text, image and link the code hardcodes today.
+
+- Keys are what the code reads — `getRecords("articles")`, `data.title`. A key can be renamed later and the old one keeps working as an alias, but it is a migration: choose them with care.
+- A collection whose records have pages of their own needs a **Slug** field — `getRecordBySlug` finds records by it.
+- Write a **Help text** for every field. Editors see it under the field; write it for someone who has never seen the code.
+- Mark a field **Sensitive** when editors keep it but the site must never receive it.
+
+### 2. Fill it in and publish once
+
+Open **Content**, move the hardcoded texts and images into records, then **Review & publish**. The site only ever reads published releases: before the first publish the delivery API answers 404 “Nothing published yet.” — `getSingle` and `getRecord` read that as `null`, `getRecords` throws.
+
+### 3. Link the repository and generate types
+
+```bash
+npx @mapled/cli auth login
+npx @mapled/cli project link
+npx @mapled/cli types generate
+npx @mapled/cli schema pull
+```
+
+Your browser opens Mapled, you pick the project and authorize; `project link` writes `mapled.json`, `types generate` writes `mapled-types.ts` — an interface per collection and single, tied together by `MapledSchema` — and `schema pull` records the schema the site is built against in `mapled/schema.json`, which `schema diff` and `doctor` compare with Mapled later. ([`@mapled/cli`](https://www.npmjs.com/package/@mapled/cli) has the details of every command used here.)
+
+### 4. Create the client
+
+Install the package and set `MAPLED_KEY` ([Install](#install)) in `.env.local` and in your hosting's environment. Then one client for the whole site:
+
+```ts
+// lib/mapled.ts
+import { createClient } from "@mapled/next";
+import type { MapledSchema } from "../mapled-types";
+
+export const mapled = createClient<MapledSchema>({ key: process.env.MAPLED_KEY! });
+```
+
+With `MapledSchema` every read is typed by its key, and a misspelled collection or field is a build error.
+
+### 5. Replace the hardcoded content with reads
+
+Read in Server Components — no client-side fetching, no loading states. A single:
+
+```tsx
+// app/page.tsx
+import { assetUrl } from "@mapled/next";
+import { mapled } from "../lib/mapled";
+
+export default async function Home() {
+  const home = await mapled.getSingle("homepage");
+  if (!home) return null; // nothing published yet
+
+  return (
+    <main>
+      <h1>{home.data.headline}</h1>
+      <p>{home.data.intro}</p>
+      {home.data.cover ? <img src={assetUrl(home.data.cover, { width: 1280 })} alt="" /> : null}
+    </main>
+  );
+}
+```
+
+A list:
+
+```tsx
+// app/blog/page.tsx
+import Link from "next/link";
+import { mapled } from "../../lib/mapled";
+
+export default async function Blog() {
+  const { records } = await mapled.getRecords("articles", { sort: "-date", limit: 20 });
+
+  return (
+    <ul>
+      {records.map((post) => (
+        <li key={post.id}>
+          <Link href={`/blog/${post.data.slug}`}>{post.data.title}</Link>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+A page per record — new records get their page without a deploy:
+
+```tsx
+// app/blog/[slug]/page.tsx
+import { notFound } from "next/navigation";
+import Markdown from "react-markdown";
+import { mapled } from "../../../lib/mapled";
+
+export async function generateStaticParams() {
+  const { records } = await mapled.getRecords("articles", { fields: ["slug"] });
+  return records.map((post) => ({ slug: post.data.slug }));
+}
+
+export default async function Article({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const post = await mapled.getRecordBySlug("articles", slug);
+  if (!post) notFound();
+
+  return (
+    <article>
+      <h1>{post.data.title}</h1>
+      <Markdown>{post.data.body}</Markdown>
+    </article>
+  );
+}
+```
+
+(`params` is a Promise since Next.js 15; on 14 it is the plain object.) Rich text is Markdown — render it with a component such as `react-markdown`, never as raw HTML. Leave in the code what editors shouldn't touch: layout, navigation structure, anything that is logic rather than content.
+
+### 6. Refresh the site on publish
+
+Reads are cached (`revalidate: 3600`) and tagged; a webhook refreshes them the moment someone publishes.
+
+```ts
+// app/api/mapled/revalidate/route.ts
+import { createRevalidateHandler } from "@mapled/next/server";
+
+export const POST = createRevalidateHandler({
+  secret: process.env.MAPLED_WEBHOOK_SECRET!,
+});
+```
+
+Deploy, then in Mapled → **Integrations** → **Your site** save `https://your-site.com/api/mapled/revalidate` as the **Revalidation webhook**, copy the **Signing secret** into `MAPLED_WEBHOOK_SECRET` (hosting env and `.env.local`), redeploy, and press **Send test ping**: the delivery shows up under **Recent deliveries** as Delivered. The URL has to be public — Mapled refuses addresses that resolve to a private network.
+
+### 7. Preview drafts
+
+```ts
+// app/api/mapled/preview/route.ts
+import { createPreviewHandler } from "@mapled/next/server";
+
+export const GET = createPreviewHandler();
+```
+
+```ts
+// app/api/mapled/preview/exit/route.ts
+import { createExitPreviewHandler } from "@mapled/next/server";
+
+export const GET = createExitPreviewHandler();
+```
+
+The **Preview** button in Mapled opens the site at the origin of the webhook URL from step 6, on exactly this path — `/api/mapled/preview` — so keep the route there. It turns on Next.js draft mode, and every read of the client switches to live drafts, uncached, with no changes in your components.
+
+### 8. Forms
+
+A contact or signup form posts straight to Mapled; submissions land in **Forms**, with e-mail notifications and spam protection. Create the form once:
+
+```bash
+npx @mapled/cli forms create "Contact"
+```
+
+and post to it from the site — see [Forms](#forms) for the component.
+
+### 9. Live data
+
+Orders, bookings, votes — records the site's backend writes and reads immediately, without Publish — go to collections created with the mode **Live data** and are reached with the server key: see [Live data](#live-data).
+
+### 10. Record the integration
+
+```bash
+npx @mapled/cli scan --write
+npx @mapled/cli bindings push
+npx @mapled/cli md pull
+```
+
+`scan` reads the code and writes `mapled/manifest.json`: which page reads which collection and field. `bindings push` sends it to Mapled, so editors see where a field appears and get a warning before a change would break the site (**Structure** → **Bindings**). `md pull` writes `MAPLED.md`, the guide for whoever works on the site next — person or AI agent. Commit `mapled.json`, `mapled-types.ts`, `mapled/schema.json`, `mapled/manifest.json` and `MAPLED.md`; never commit an env file.
+
+### 11. Check everything
+
+```bash
+npx @mapled/cli doctor
+```
+
+It checks the integration from both sides — the repository and what Mapled sees of the deployed site. The list below is what an agent's setup has to pass before Mapled calls it complete; `doctor` answers all of it except the last two lines, which are yours to check:
+
+- the site reads content from Mapled (“Site reads content — Last read …”);
+- a publish refreshes it (“Publish webhook — Delivered …”);
+- **Preview** in Mapled opens the site with drafts (“Preview on the site — Responds at …”);
+- bindings are pushed and healthy, and the integration is in sync (“Bindings”, “Integration”);
+- no env file or secret is tracked by git (“Secrets in git”);
+- every field has a help text (**Structure** → **Collections**);
+- the site builds.
+
+Later, when the structure changes in Mapled, `npx @mapled/cli schema diff` says what changed and whether it breaks the site; after updating the code, run `types generate`, `scan --write`, `bindings push` and `md pull` again.
+
 ## Read published content
 
 ```ts
@@ -63,6 +260,16 @@ await mapled.getRecords("artcles");                       // type error — no s
 
 Without a schema the client behaves as before: any key, `Record<string, unknown>` data, or the type you name per call (`getRecords<Article>("articles")`). `createAppClient<MapledSchema>` types live data the same way — `db.create("orders", data)` wants an `Order`. `mapled doctor` tells you when the generated file is behind the schema.
 
+### Renamed fields
+
+When a field's key is renamed in Mapled, nothing breaks: the old key stays as an alias — delivered next to the new one, accepted in `filter`, `sort`, `fields`, `expand` and in live-data writes — until someone removes it in Field settings. Answers that still serve a previous key name it (`aliases: { products: { price: "amount" } }` on a list result), and outside production the client says so once per key:
+
+```
+[mapled] “price” in “products” was renamed to “amount”. The old key keeps working until its alias is removed in Mapled — use “amount” instead.
+```
+
+Move the code to the new key, run `mapled types generate` (the old key is typed `@deprecated` until then), and remove the alias. In production the client stays silent.
+
 ### Pin a release
 
 A page that makes several reads can pin them all to one release, so a publish landing mid-render can't mix two versions:
@@ -104,7 +311,9 @@ export const POST = createRevalidateHandler({
 });
 ```
 
-Then in Mapled (project → Integrations → **Your site**) set the revalidation webhook to `https://your-site.com/api/mapled/revalidate` and copy the signing secret into `MAPLED_WEBHOOK_SECRET`. Every publish sends a signed ping; the handler verifies the `x-mapled-signature` HMAC and revalidates the `mapled` tags.
+Then in Mapled (**Integrations** → **Your site**) set the revalidation webhook to `https://your-site.com/api/mapled/revalidate` and copy the signing secret into `MAPLED_WEBHOOK_SECRET`. Every publish sends a signed ping; the handler verifies the `x-mapled-signature` HMAC and revalidates the `mapled` tags.
+
+Each ping is tried up to three times (after 2 and 6 seconds, 5 seconds to answer); **Recent deliveries** keeps them for 30 days, and a failed one can be sent again from there. **Rotate secret** replaces the signing secret at once — deliveries fail until the site has the new one.
 
 ## Preview drafts
 
@@ -124,6 +333,64 @@ export const GET = createExitPreviewHandler();
 
 The **Preview** button in Mapled opens your site through a one-time link: the route turns on Next.js draft mode, and every `getRecords`/`getRecord`/`getSingle` call automatically switches to live drafts, uncached. No code changes in your components — the client detects draft mode on its own. Sessions last two hours; `/api/mapled/preview/exit` leaves preview.
 
+Mapled finds the site by the revalidation webhook's URL — preview opens at its origin, on `/api/mapled/preview` — so set the webhook up first and keep the route on that path.
+
+## Forms
+
+A form is created once — `npx @mapled/cli forms create "Contact"`, or by your AI agent — and gets a key (`contact`). The site posts submissions as flat JSON with the delivery key; they show up in Mapled under **Forms** right away, and the form's recipients — the project's owners, unless its settings name others — get an e-mail. Forms never wait for Publish.
+
+```tsx
+// app/contact/ContactForm.tsx
+"use client";
+
+import { useState, type FormEvent } from "react";
+
+const CONSENT = "I agree to be contacted about my request.";
+
+export function ContactForm() {
+  const [state, setState] = useState<"idle" | "sending" | "sent" | "failed">("idle");
+
+  async function submit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    setState("sending");
+    const form = new FormData(event.currentTarget);
+    const res = await fetch("https://api.mapled.io/v1/delivery/forms/contact", {
+      method: "POST",
+      headers: { "content-type": "application/json", "x-mapled-key": process.env.NEXT_PUBLIC_MAPLED_KEY! },
+      body: JSON.stringify({
+        name: form.get("name"),
+        email: form.get("email"),
+        message: form.get("message"),
+        _gotcha: form.get("_gotcha"), // the honeypot: people leave it empty
+        _consent: form.get("consent") ? CONSENT : undefined,
+        _page: window.location.pathname,
+      }),
+    });
+    setState(res.ok ? "sent" : "failed");
+  }
+
+  if (state === "sent") return <p>Thank you — we'll be in touch.</p>;
+  return (
+    <form onSubmit={submit}>
+      <input name="name" required />
+      <input name="email" type="email" required />
+      <textarea name="message" required />
+      <input name="_gotcha" tabIndex={-1} autoComplete="off" aria-hidden="true" style={{ display: "none" }} />
+      <label>
+        <input name="consent" type="checkbox" required /> {CONSENT}
+      </label>
+      <button disabled={state === "sending"}>Send</button>
+      {state === "failed" ? <p>That didn't go through. Try again in a minute.</p> : null}
+    </form>
+  );
+}
+```
+
+- The endpoint is open to browsers (CORS) and takes the **delivery key** — the one key that is safe in client code. Expose it as `NEXT_PUBLIC_MAPLED_KEY`; never the server key or the webhook secret. To keep even that out of the bundle, post from a Server Action with `MAPLED_KEY` instead — all visitors then share your server's address for the limit below.
+- The body is one flat object: up to 50 fields of text (5,000 characters), numbers and booleans. Keys starting with `_` are instructions, not answers: `_gotcha` (a hidden field bots fill in — such submissions are accepted and filed as spam), `_consent` (the exact label of the consent checkbox the visitor ticked, kept as evidence), `_page` (where the form was), `_test: true` (a test submission: no e-mail, not counted).
+- `201 { "ok": true }` on success. `400 VALIDATION_FAILED` for a body of another shape, `404` for an unknown key or form, `429 RATE_LIMITED` past 30 submissions a minute per form and address, `429 FORMS_LIMIT` when the project's monthly submissions are used up, `410 PROJECT_ARCHIVED` for an archived project.
+- `npx @mapled/cli forms list` shows the project's forms and their URLs.
+
 ## Live data
 
 Operational collections skip the publish cycle — saves take effect immediately. Your site's backend reads **and writes** them through the Application Data API with the project's **server key** (Mapled: Integrations → Your site). Server-side only; the key must never reach the browser.
@@ -145,12 +412,42 @@ await db.remove("orders", id);
 
 The server key reaches only operational collections with access class `public`/`server` — editorial content, internal and sensitive collections stay out of reach, and it grants nothing on the Management API.
 
+## Without Next.js: the HTTP API
+
+The client is a thin layer over a plain HTTP API, so any site — or a build script — can read Mapled. The base URL is `https://api.mapled.io`; every request carries the delivery key in `x-mapled-key`.
+
+| Request | Answer |
+| --- | --- |
+| `GET /v1/delivery/collections/{collection}/records` | `{ records: [{ id, data, expanded? }], total, release }` |
+| `GET /v1/delivery/collections/{collection}/records/{id}` | `{ record, release }` — 404 when it isn't in the release |
+| `GET /v1/delivery/collections/{collection}/records/by-slug/{slug}` | `{ record, release }` |
+| `GET /v1/delivery/singles/{single}` | `{ record, release }` — `record` is `null` while the single is empty |
+| `GET /v1/delivery/release` | `{ release, publishedAt }` — the release being served now; `null`s before the first publish |
+| `POST /v1/delivery/forms/{form}` | `201 { ok: true }` — see [Forms](#forms) |
+
+```bash
+curl -H "x-mapled-key: $MAPLED_KEY" \
+  "https://api.mapled.io/v1/delivery/collections/articles/records?filter[featured]=true&filter[date][gte]=2026-01-01&sort=-date&limit=10&expand=author&fields=title,slug"
+```
+
+- Lists take `filter[field]=value` or `filter[field][op]=value` (`eq`, `ne`, `lt`, `lte`, `gt`, `gte`, `in` — comma-separated, `contains`), `sort=field` / `sort=-field`, `limit` (1–100, default 100) and `offset`. Every read takes `expand` (relation keys, dotted for a second level), `fields` and `release=N` to read a published release by its number. A query the schema can't answer is a 400 `INVALID_QUERY` that says why.
+- Only published content of collections with access **Public** is served; sensitive fields are never in an answer. Image and file values are asset ids — `https://api.mapled.io/files/{id}` is the file, with `?w=`, `h=`, `fit=`, `fmt=`, `q=` for a resized variant.
+- Answers are per key — `Cache-Control: private` — with an `ETag`: send it back as `If-None-Match` and an unchanged answer is a 304. A read pinned with `release=N` never changes and may be cached for good. `GET /v1/delivery/release` is the cheap way to learn that something was published.
+- Errors share one envelope: `{ error: { code, message, requestId } }`. A key gets 1,200 requests a minute; past that, 429 `RATE_LIMITED` with `retry-after`.
+- The publish webhook is a `POST` with a JSON body `{ event, project, release, at, id }` and the headers `x-mapled-event` (`release.published`, `project.restored` or `test`), `x-mapled-event-id` (the same on every retry — use it to deduplicate), `x-mapled-attempt` and `x-mapled-signature`: `sha256=` followed by the hex HMAC-SHA256 of the raw body with the signing secret. Compare in constant time, answer 2xx within 5 seconds. `verifySignature` from `@mapled/next/server` does the check anywhere Web Crypto exists.
+- Live data: `GET` / `POST /v1/app/collections/{collection}/records` and `GET` / `PATCH` / `DELETE /v1/app/collections/{collection}/records/{id}` with the server key in `x-mapled-server-key`; writes send `{ "data": { … } }`.
+
+Preview (drafts on the site) is built on Next.js draft mode and ships with this package only.
+
 ## API
 
 - `createClient({ key, apiUrl?, release? })` → `getRecords(collection, opts?)`, `getRecord(collection, id, opts?)`, `getRecordBySlug(collection, slug, opts?)`, `getSingle(key, opts?)`, `getRelease()`; `createClient<MapledSchema>(…)` with the generated `MapledSchema` types every read by its key (`MapledClient<S>`, `MapledAppClient<S>` name the typed clients)
 - list `opts`: `filter` (a value for equality, or `{ eq, ne, lt, lte, gt, gte, in, contains }` — text takes eq/ne/in/contains, numbers and dates comparisons, booleans eq/ne, image and relation ids eq/ne/in; a one-to-many relation matches when it includes the id), `sort` (`"field"` / `"-field"`, not on relations or images), `limit` (≤100), `offset`
 - every read: `expand` (relation keys, dotted for a second level), `fields` (data keys to keep), `release` (pin to a published release), `revalidate`, `tags`; a query the schema can't answer fails with a 400 `INVALID_QUERY` message, and errors carry the API's `code` on `MapledError`
+- `createAppClient({ serverKey, apiUrl? })` → `list(collection, opts?)`, `get(collection, id)`, `create(collection, data)`, `update(collection, id, data)`, `remove(collection, id)`
+- `assetUrl(id, { width?, height?, fit?, format?, quality?, apiUrl? })` — URL of an image or file value
 - `createRevalidateHandler({ secret, tags? })` — App Router `POST` handler
+- `createPreviewHandler({ apiUrl?, appUrl? })`, `createExitPreviewHandler()` — App Router `GET` handlers of the preview routes
 - `verifySignature(secret, body, signature)` — if you'd rather build your own handler
 
 The delivery key only reads published, public content — safe to use anywhere.

package/dist/index.d.ts

@@ -51,6 +51,10 @@ export type ListResult<T = Record<string, unknown>> = {
     records: MapledRecord<T>[];
     total: number;
     release: number;
+    /** Renamed fields whose previous keys this answer still serves, by
+        collection: `{ products: { price: "amount" } }`. Absent when nothing
+        was renamed. Outside production the SDK warns about each once. */
+    aliases?: Record<string, Record<string, string>>;
 };
 export type ImageOptions = {
     /** Snapped up to the nearest preset (64 … 2560); never upscaled past the source. */

package/dist/index.js

@@ -1,6 +1,34 @@
 /** Mapled delivery client for Next.js sites.
     Reads published content only — pair it with the revalidation webhook
     handler from "@mapled/next/server" for instant updates on publish. */
+/** Renamed fields (previous keys): Mapled keeps serving a renamed field
+    under its old key — and accepting it in filters, sorts and writes —
+    until the alias is removed in Field settings, and names such keys in
+    its answers. Outside production each is reported once per process, so
+    the site moves to the new key before the alias goes. */
+const KEY_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const reported = new Set();
+function reportAliases(body) {
+    if (typeof process !== "undefined" && process.env?.NODE_ENV === "production")
+        return;
+    const aliases = body?.aliases;
+    if (!aliases || typeof aliases !== "object")
+        return;
+    for (const [collection, keys] of Object.entries(aliases)) {
+        if (!keys || typeof keys !== "object" || !KEY_RE.test(collection))
+            continue;
+        for (const [previous, current] of Object.entries(keys)) {
+            // keys are the project's content: only what looks like a key is printed
+            if (typeof current !== "string" || !KEY_RE.test(previous) || !KEY_RE.test(current))
+                continue;
+            const id = `${collection}.${previous}`;
+            if (reported.has(id))
+                continue;
+            reported.add(id);
+            console.warn(`[mapled] “${previous}” in “${collection}” was renamed to “${current}”. The old key keeps working until its alias is removed in Mapled — use “${current}” instead.`);
+        }
+    }
+}
 /** URL of an image or file value (an asset id) — the original, or a
     resized variant made on first request and cached from then on. */
 export function assetUrl(id, opts = {}) {
@@ -95,7 +123,9 @@ export function createClient(config) {
         const res = await fetch(`${base}${path}${qs ? `?${qs}` : ""}`, init);
         if (!res.ok)
             throw await failure(res);
-        return { status: res.status, body: (await res.json()) };
+        const body = (await res.json());
+        reportAliases(body);
+        return { status: res.status, body };
     }
     /** expand / fields on every read. */
     const readParams = (search, opts) => {
@@ -198,7 +228,9 @@ export function createAppClient(config) {
             }
             throw new MapledError(res.status, message);
         }
-        return (await res.json());
+        const body = (await res.json());
+        reportAliases(body);
+        return body;
     }
     const collectionPath = (c) => `/v1/app/collections/${encodeURIComponent(c)}/records`;
     const client = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapled/next",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Read published Mapled content in a Next.js site \u2014 delivery client, ISR tags, and a revalidation webhook handler.",
   "license": "MIT",
   "homepage": "https://mapled.io",