npm - @mapled/next - Versions diffs - 0.7.1 → 0.8.0 - Mend

@mapled/next 0.7.1 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/README.md CHANGED Viewed

@@ -1,12 +1,12 @@
 # @mapled/next
-Read published [Mapled](https://mapled.io) content in a Next.js site — a delivery client with ISR cache tags, plus a revalidation webhook handler so publishes show up instantly.
+Read published [Mapled](https://mapled.io) content in a Next.js site — a delivery client with ISR cache tags, a revalidation webhook handler so publishes show up instantly, and live updates for the tabs that are already open.
 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)
+- Reference: [Read published content](#read-published-content) • [Rich text](#rich-text) • [Images](#images) • [Refresh on publish](#refresh-on-publish) • [Live updates](#live-updates) • [Preview drafts](#preview-drafts) • [Forms](#forms) • [Live data](#live-data) • [Without Next.js: the HTTP API](#without-nextjs-the-http-api) • [API](#api)
 ## Install
@@ -153,6 +153,8 @@ export const POST = createRevalidateHandler({
 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.
+Optional: pages that are already open can follow a publish too, without a reload — a route and one component, see [Live updates](#live-updates).
 ### 7. Preview drafts
 ```ts
@@ -315,6 +317,64 @@ Then in Mapled (**Integrations** → **Your site**) set the revalidation webhook
 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.
+## Live updates
+The webhook refreshes the site's cache; a page someone already has open still shows what it rendered. Two files make open tabs follow Publish as well. A route that says which release the site serves:
+```ts
+// app/api/mapled/release/route.ts
+import { createReleaseHandler } from "@mapled/next/server";
+export const GET = createReleaseHandler({ key: process.env.MAPLED_KEY! });
+```
+and one component in the root layout:
+```tsx
+// app/layout.tsx
+import type { ReactNode } from "react";
+import { MapledLive } from "@mapled/next/live";
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        {children}
+        <MapledLive />
+      </body>
+    </html>
+  );
+}
+```
+`<MapledLive />` renders nothing. While the tab is visible it asks the route every 10 seconds (`interval`, in seconds), and when a publish lands it calls `router.refresh()`: Server Components re-render with the new release in place — scroll position and client state stay. A hidden tab doesn't ask; it checks the moment it is shown again. To offer the update instead of applying it under the reader, pass `onPublish`:
+```tsx
+"use client";
+import { useRouter } from "next/navigation";
+import { useState } from "react";
+import { MapledLive } from "@mapled/next/live";
+export function UpdateNotice() {
+  const router = useRouter();
+  const [fresh, setFresh] = useState(false);
+  return (
+    <>
+      <MapledLive onPublish={() => setFresh(true)} />
+      {fresh ? <button onClick={() => { router.refresh(); setFresh(false); }}>New content — refresh</button> : null}
+    </>
+  );
+}
+```
+- It is polling, and it is cheap: tabs ask **your** route, never Mapled. The route reuses one answer for `ttl` seconds (default 5) — in the instance and, through `s-maxage`, at the CDN in front of it — and a check that finds nothing new is a 304. However many tabs are open, Mapled hears from the site a few times a minute, and the key's rate limit is left for reads.
+- The route reads the release under the same `mapled` cache tag as the content, so it moves when the webhook refreshes the cache and not before — a tab that refreshes on it never renders the old release again. Live updates therefore need the webhook from [Refresh on publish](#refresh-on-publish); without it both change only when their ISR window (`revalidate`, 3600 by default) runs out.
+- The route answers `{ release, publishedAt }` — the number of publishes and the time of the last one, nothing else — and may be cached by anyone. While Mapled can't be reached it keeps answering the last release it knew.
+- Expect a publish to reach an open tab in about ten seconds with the defaults. `<MapledLive interval={3} />` and `createReleaseHandler({ key, ttl: 1 })` make it quicker at the price of more requests to your site.
+Outside React, `watchRelease({ onPublish })` from `@mapled/next` is the same watch as a plain function — it returns the function that stops it.
 ## Preview drafts
 Mount the preview routes:
@@ -432,7 +492,7 @@ curl -H "x-mapled-key: $MAPLED_KEY" \
 - 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.
+- 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: relay it from a route of your own server, and `watchRelease({ endpoint, onPublish })` from `@mapled/next` — no framework in it — tells open tabs ([Live updates](#live-updates)).
 - 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": { … } }`.
@@ -448,6 +508,7 @@ Preview (drafts on the site) is built on Next.js draft mode and ships with this
 - `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
+- `createReleaseHandler({ key, apiUrl?, ttl?, revalidate? })` — App Router `GET` handler of the release route; `<MapledLive endpoint? interval? onPublish? />` from `@mapled/next/live` and `watchRelease({ endpoint?, interval?, onPublish })` ask it
 - `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 CHANGED Viewed

@@ -1,6 +1,7 @@
 /** 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. */
+export { watchRelease, type Release, type WatchOptions } from "./watch.js";
 export type MapledRecord<T = Record<string, unknown>> = {
     id: string;
     data: T;
@@ -158,4 +159,3 @@ export declare function createAppClient<S extends ContentSchema = ContentSchema>
     serverKey: string;
     apiUrl?: string;
 }): MapledAppClient<S>;
-export {};

package/dist/index.js CHANGED Viewed

@@ -1,6 +1,7 @@
 /** 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. */
+export { watchRelease } from "./watch.js";
 /** 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

package/dist/live.d.ts ADDED Viewed

@@ -0,0 +1,12 @@
+import { type Release } from "./watch.js";
+export type { Release } from "./watch.js";
+export type MapledLiveProps = {
+    /** Where the release route is mounted (default "/api/mapled/release"). */
+    endpoint?: string;
+    /** Seconds between checks while the tab is visible (default 10, at least 2). */
+    interval?: number;
+    /** Runs instead of the refresh — to offer "New content — refresh"
+        rather than change the page under the reader. */
+    onPublish?: (next: Release, previous: number | null) => void;
+};
+export declare function MapledLive({ endpoint, interval, onPublish }: MapledLiveProps): null;

package/dist/live.js ADDED Viewed

@@ -0,0 +1,32 @@
+"use client";
+/** Open tabs follow Publish. Render it once, in the root layout:
+    app/layout.tsx:
+      import { MapledLive } from "@mapled/next/live";
+      <body>{children}<MapledLive /></body>
+    It asks the release route (`createReleaseHandler` from
+    "@mapled/next/server", mounted at /api/mapled/release) every few
+    seconds and, when a publish lands, refreshes the page's server
+    components in place — scroll position and client state stay. */
+import { useRouter } from "next/navigation";
+import { useEffect, useRef } from "react";
+import { watchRelease } from "./watch.js";
+export function MapledLive({ endpoint, interval, onPublish }) {
+    const router = useRouter();
+    const custom = useRef(onPublish);
+    useEffect(() => {
+        custom.current = onPublish;
+    }, [onPublish]);
+    useEffect(() => watchRelease({
+        endpoint,
+        interval,
+        onPublish: (next, previous) => {
+            if (custom.current)
+                custom.current(next, previous);
+            else
+                router.refresh();
+        },
+    }), [endpoint, interval, router]);
+    return null;
+}

package/dist/server.d.ts CHANGED Viewed

@@ -25,3 +25,19 @@ export declare function createRevalidateHandler(options: {
         client fetch. */
     tags?: string[];
 }): (req: Request) => Promise<Response>;
+/** GET handler for the release route (mount at /api/mapled/release):
+    the release this site serves right now, for `<MapledLive />` from
+    "@mapled/next/live" to ask about. The pointer is read under the
+    "mapled" tag like the content is, so it moves when the publish webhook
+    refreshes the cache and not before — a tab that refreshes on it
+    renders the new release, never the old one again. One answer is reused
+    for `ttl` seconds, in this instance and at the CDN in front of it:
+    however many tabs ask, Mapled hears from the site a few times a minute. */
+export declare function createReleaseHandler(options: {
+    key: string;
+    apiUrl?: string;
+    /** Seconds one answer is reused (default 5, at least 1). */
+    ttl?: number;
+    /** ISR window of the pointer, the same as a read's (default 3600 — the webhook keeps it fresh). */
+    revalidate?: number | false;
+}): (req: Request) => Promise<Response>;

package/dist/server.js CHANGED Viewed

@@ -99,3 +99,72 @@ export function createRevalidateHandler(options) {
         return Response.json({ revalidated: true });
     };
 }
+/** GET handler for the release route (mount at /api/mapled/release):
+    the release this site serves right now, for `<MapledLive />` from
+    "@mapled/next/live" to ask about. The pointer is read under the
+    "mapled" tag like the content is, so it moves when the publish webhook
+    refreshes the cache and not before — a tab that refreshes on it
+    renders the new release, never the old one again. One answer is reused
+    for `ttl` seconds, in this instance and at the CDN in front of it:
+    however many tabs ask, Mapled hears from the site a few times a minute. */
+export function createReleaseHandler(options) {
+    if (!options.key)
+        throw new Error("Mapled: a delivery key is required.");
+    const base = (options.apiUrl ?? "https://api.mapled.io").replace(/\/+$/, "");
+    const ttlMs = Math.max(1, options.ttl ?? 5) * 1000;
+    let held = null;
+    /** when Mapled was last asked — an answer or a failure, either waits a ttl */
+    let askedAt = 0;
+    let loading = null;
+    let complained = false;
+    async function load() {
+        try {
+            const init = {
+                headers: { "x-mapled-key": options.key },
+                next: { revalidate: options.revalidate ?? 3600, tags: ["mapled"] },
+            };
+            const res = await fetch(`${base}/v1/delivery/release`, init);
+            if (!res.ok)
+                throw new Error(`Mapled answered ${res.status}`);
+            const body = (await res.json());
+            const release = body?.release ?? null;
+            const publishedAt = body?.publishedAt ?? null;
+            const published = Number.isInteger(release) && release >= 1 && typeof publishedAt === "string";
+            if (!published && release !== null)
+                throw new Error("Mapled's answer wasn't a release");
+            held = published ? { release, publishedAt } : { release: null, publishedAt: null };
+            complained = false;
+        }
+        catch (err) {
+            // the last answer stays good while Mapled can't be reached
+            if (!complained) {
+                complained = true;
+                console.error(`[mapled] The release route can't read the live release: ${err instanceof Error ? err.message : "request failed"}.`);
+            }
+        }
+        finally {
+            askedAt = Date.now();
+        }
+    }
+    return async function GET(req) {
+        // read first: a handler that looks at its request is never prerendered
+        const asked = req.headers.get("if-none-match");
+        if (Date.now() - askedAt >= ttlMs) {
+            loading ??= load().finally(() => {
+                loading = null;
+            });
+            await loading;
+        }
+        if (!held) {
+            return Response.json({ error: "The live release isn't available right now." }, { status: 502, headers: { "cache-control": "no-store" } });
+        }
+        // the CDN's copy lives no longer than this instance's
+        const left = Math.max(1, Math.ceil((ttlMs - (Date.now() - askedAt)) / 1000));
+        const etag = `W/"r${held.release ?? 0}"`;
+        const headers = { "cache-control": `public, max-age=0, s-maxage=${left}`, etag };
+        if (asked && asked.split(",").some((t) => t.trim().replace(/^W\//, "") === etag.slice(2))) {
+            return new Response(null, { status: 304, headers });
+        }
+        return Response.json(held, { headers });
+    };
+}

package/dist/watch.d.ts ADDED Viewed

@@ -0,0 +1,23 @@
+/** Publish notifications for open tabs: the page asks its own server
+    which release is live (the route `createReleaseHandler` from
+    "@mapled/next/server" serves) and hears about it when that moves.
+    Framework-free on purpose — `<MapledLive />` from "@mapled/next/live"
+    is this plus `router.refresh()`. */
+export type Release = {
+    release: number;
+    publishedAt: string;
+};
+export type WatchOptions = {
+    /** Where the release route is mounted (default "/api/mapled/release"). */
+    endpoint?: string;
+    /** Seconds between checks while the tab is visible (default 10, at least 2). */
+    interval?: number;
+    /** A publish landed: `next` is live now; `previous` is the release the
+        watch knew before — null when nothing was published yet. */
+    onPublish: (next: Release, previous: number | null) => void;
+};
+/** Starts watching; returns the function that stops it. The first answer
+    is where the watch starts from; `onPublish` runs once per release that
+    comes after it. A hidden tab doesn't ask — it checks the moment it is
+    shown again — and a route that fails is asked less and less often. */
+export declare function watchRelease(options: WatchOptions): () => void;

package/dist/watch.js ADDED Viewed

@@ -0,0 +1,96 @@
+/** Publish notifications for open tabs: the page asks its own server
+    which release is live (the route `createReleaseHandler` from
+    "@mapled/next/server" serves) and hears about it when that moves.
+    Framework-free on purpose — `<MapledLive />` from "@mapled/next/live"
+    is this plus `router.refresh()`. */
+const DEFAULT_ENDPOINT = "/api/mapled/release";
+const MAX_BACKOFF_MS = 5 * 60_000;
+/** The route's answer — null before the first publish — or undefined
+    when it isn't one. */
+function pointer(body) {
+    if (!body || typeof body !== "object")
+        return undefined;
+    const { release, publishedAt } = body;
+    if (release === null)
+        return null;
+    if (!Number.isInteger(release) || release < 1 || typeof publishedAt !== "string")
+        return undefined;
+    return { release: release, publishedAt };
+}
+/** Starts watching; returns the function that stops it. The first answer
+    is where the watch starts from; `onPublish` runs once per release that
+    comes after it. A hidden tab doesn't ask — it checks the moment it is
+    shown again — and a route that fails is asked less and less often. */
+export function watchRelease(options) {
+    const endpoint = options.endpoint ?? DEFAULT_ENDPOINT;
+    const everyMs = Math.max(2, options.interval ?? 10) * 1000;
+    const doc = typeof document === "undefined" ? null : document;
+    /** undefined until the first answer; null while nothing is published */
+    let seen;
+    let failures = 0;
+    let stopped = false;
+    let timer;
+    let inFlight = null;
+    const visible = () => !doc || doc.visibilityState !== "hidden";
+    const schedule = () => {
+        if (stopped || !visible())
+            return;
+        timer = setTimeout(check, Math.min(everyMs * 2 ** failures, MAX_BACKOFF_MS));
+    };
+    async function check() {
+        if (stopped || inFlight)
+            return;
+        const request = new AbortController();
+        inFlight = request;
+        let news = null;
+        try {
+            // no-cache: the browser revalidates by ETag, so a quiet check is a 304
+            const res = await fetch(endpoint, { cache: "no-cache", headers: { accept: "application/json" }, signal: request.signal });
+            const now = res.ok ? pointer(await res.json()) : undefined;
+            if (stopped)
+                return;
+            if (now === undefined) {
+                failures += 1;
+            }
+            else {
+                failures = 0;
+                if (seen === undefined) {
+                    seen = now ? now.release : null;
+                }
+                else if (now && now.release > (seen ?? 0)) {
+                    // releases only grow (a rollback is a new one): an answer from a
+                    // server that hasn't caught up yet never looks like news
+                    news = { next: now, previous: seen };
+                    seen = now.release;
+                }
+            }
+        }
+        catch {
+            if (stopped)
+                return;
+            failures += 1;
+        }
+        finally {
+            if (inFlight === request)
+                inFlight = null;
+        }
+        schedule();
+        // after the next check is set: a callback that throws doesn't end the watch
+        if (news)
+            options.onPublish(news.next, news.previous);
+    }
+    const onVisibility = () => {
+        clearTimeout(timer);
+        if (visible())
+            void check();
+    };
+    doc?.addEventListener("visibilitychange", onVisibility);
+    if (visible())
+        void check();
+    return () => {
+        stopped = true;
+        clearTimeout(timer);
+        inFlight?.abort();
+        doc?.removeEventListener("visibilitychange", onVisibility);
+    };
+}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@mapled/next",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "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",
@@ -27,6 +27,10 @@
     "./server": {
       "types": "./dist/server.d.ts",
       "default": "./dist/server.js"
+    },
+    "./live": {
+      "types": "./dist/live.d.ts",
+      "default": "./dist/live.js"
     }
   },
   "files": [