@mapled/next 0.4.0 → 0.5.0

package/README.md

@@ -47,6 +47,18 @@ posts[0].expanded?.author; // { id, data: { name: "Ada" } } or null
 
 Every call reads the latest **published release** — drafts never leak. Fetches are tagged `mapled` and `mapled:<collection>` and default to `revalidate: 3600`; the webhook below refreshes them the moment someone publishes.
 
+### 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:
+
+```ts
+const live = await mapled.getRelease(); // { release: 12, publishedAt } — null before the first publish
+const { records } = await mapled.getRecords("articles", { release: live!.release });
+const about = await mapled.getRecordBySlug("pages", "about", { release: live!.release });
+```
+
+`createClient({ key, release: 12 })` pins every read — a way to hold a site on a known-good release without publishing anything. A release never changes, so pinned reads are cached until the next publish (`revalidate: false` unless you pass your own); a release that doesn't exist fails with a 404 `RELEASE_NOT_FOUND` rather than reading as a missing record. In preview (draft mode) the pin is dropped: drafts are unversioned.
+
 ## Rich text
 
 `rich_text` values are Markdown (headings, lists, links, bold/italic, images as `![alt](url)`). Render them with a Markdown component such as `react-markdown` — never inject them as raw HTML.
@@ -119,9 +131,9 @@ The server key reaches only operational collections with access class `public`/`
 
 ## API
 
-- `createClient({ key, apiUrl? })` → `getRecords(collection, opts?)`, `getRecord(collection, id, opts?)`, `getRecordBySlug(collection, slug, opts?)`, `getSingle(key, opts?)`
+- `createClient({ key, apiUrl?, release? })` → `getRecords(collection, opts?)`, `getRecord(collection, id, opts?)`, `getRecordBySlug(collection, slug, opts?)`, `getSingle(key, opts?)`, `getRelease()`
 - 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), `revalidate`, `tags`; a query the schema can't answer fails with a 400 `INVALID_QUERY` message
+- 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`
 - `createRevalidateHandler({ secret, tags? })` — App Router `POST` handler
 - `verifySignature(secret, body, signature)` — if you'd rather build your own handler
 

package/dist/index.d.ts

@@ -31,6 +31,12 @@ export type ReadOptions = {
     revalidate?: number | false;
     /** Extra cache tags on top of "mapled" and "mapled:<collection>". */
     tags?: string[];
+    /** Read this release instead of the latest one: pin a render to the
+        number its first read returned so a publish landing mid-render can't
+        mix two versions, or hold a site on a known-good release. A release
+        never changes, so pinned reads stay cached until the next publish
+        (`revalidate: false` unless you say otherwise). */
+    release?: number;
 };
 export type ListOptions = ReadOptions & {
     /** Filters on top-level fields, ANDed: { slug: "about", price: { gte: 10 } }. */
@@ -63,7 +69,9 @@ export type ImageOptions = {
 export declare function assetUrl(id: string, opts?: ImageOptions): string;
 export declare class MapledError extends Error {
     status: number;
-    constructor(status: number, message: string);
+    /** The API's error code — "NOT_FOUND", "INVALID_QUERY", "RELEASE_NOT_FOUND", … */
+    code: string | undefined;
+    constructor(status: number, message: string, code?: string);
 }
 export type MapledClient = ReturnType<typeof createClient>;
 export type MapledAppClient = ReturnType<typeof createAppClient>;
@@ -82,6 +90,7 @@ export type AppListOptions = {
 export declare function createClient(config: {
     key: string;
     apiUrl?: string;
+    release?: number;
 }): {
     /** Published records of a collection, with filters/sort/pagination. */
     getRecords<T = Record<string, unknown>>(collection: string, opts?: ListOptions): Promise<ListResult<T>>;
@@ -91,6 +100,14 @@ export declare function createClient(config: {
     getRecordBySlug<T = Record<string, unknown>>(collection: string, slug: string, opts?: ReadOptions): Promise<MapledRecord<T> | null>;
     /** The record of a single (e.g. "homepage"), or null before publish. */
     getSingle<T = Record<string, unknown>>(key: string, opts?: ReadOptions): Promise<MapledRecord<T> | null>;
+    /** The release the site is reading right now — the latest published
+        one, with the moment it went live — or null before the first
+        publish. Never cached: it's the one short-lived pointer of the
+        delivery API; pass its number as `release` to pin a render. */
+    getRelease(): Promise<{
+        release: number;
+        publishedAt: string;
+    } | null>;
 };
 /** Live data (operational collections): the site's backend reads and
     writes records that take effect immediately — no publish involved.

package/dist/index.js

@@ -21,12 +21,17 @@ export function assetUrl(id, opts = {}) {
 }
 export class MapledError extends Error {
     status;
-    constructor(status, message) {
+    /** The API's error code — "NOT_FOUND", "INVALID_QUERY", "RELEASE_NOT_FOUND", … */
+    code;
+    constructor(status, message, code) {
         super(message);
         this.name = "MapledError";
         this.status = status;
+        this.code = code;
     }
 }
+const isRelease = (n) => Number.isInteger(n) && n >= 1;
+const badRelease = () => new Error("Mapled: release must be a positive whole number.");
 /** The draft session cookie set by the preview route. When Next draft
     mode is on, every read switches to live drafts, uncached. Outside a
     Next request context this quietly resolves to null. */
@@ -46,9 +51,33 @@ export function createClient(config) {
     const base = (config.apiUrl ?? "https://api.mapled.io").replace(/\/+$/, "");
     if (!config.key)
         throw new Error("Mapled: a delivery key is required.");
+    if (config.release !== undefined && !isRelease(config.release))
+        throw badRelease();
+    /** The API's error envelope as a MapledError. */
+    async function failure(res) {
+        let message = `Mapled request failed (${res.status}).`;
+        let code;
+        try {
+            const parsed = (await res.json());
+            if (parsed.error?.message)
+                message = parsed.error.message;
+            if (typeof parsed.error?.code === "string")
+                code = parsed.error.code;
+        }
+        catch {
+            /* non-JSON error body */
+        }
+        return new MapledError(res.status, message, code);
+    }
     async function call(path, search, opts, cacheTags) {
-        const qs = search.toString();
         const draft = await draftSession();
+        const release = opts.release ?? config.release;
+        if (release !== undefined && !isRelease(release))
+            throw badRelease();
+        // drafts are unversioned: a pin only shapes published reads
+        if (release !== undefined && !draft)
+            search.set("release", String(release));
+        const qs = search.toString();
         const init = draft
             ? {
                 headers: { "x-mapled-key": config.key, "x-mapled-draft": draft },
@@ -57,23 +86,15 @@ export function createClient(config) {
             : {
                 headers: { "x-mapled-key": config.key },
                 next: {
-                    revalidate: opts.revalidate ?? 3600,
+                    // a release never changes: a pinned read stays cached until
+                    // the publish webhook revalidates the tags
+                    revalidate: opts.revalidate ?? (release !== undefined ? false : 3600),
                     tags: ["mapled", ...cacheTags, ...(opts.tags ?? [])],
                 },
             };
         const res = await fetch(`${base}${path}${qs ? `?${qs}` : ""}`, init);
-        if (!res.ok) {
-            let message = `Mapled request failed (${res.status}).`;
-            try {
-                const parsed = (await res.json());
-                if (parsed.error?.message)
-                    message = parsed.error.message;
-            }
-            catch {
-                /* non-JSON error body */
-            }
-            throw new MapledError(res.status, message);
-        }
+        if (!res.ok)
+            throw await failure(res);
         return { status: res.status, body: (await res.json()) };
     }
     /** expand / fields on every read. */
@@ -90,8 +111,10 @@ export function createClient(config) {
             return body.record;
         }
         catch (err) {
-            if (err instanceof MapledError && err.status === 404)
+            // a missing record is null; a missing release is a configuration error
+            if (err instanceof MapledError && err.status === 404 && err.code !== "RELEASE_NOT_FOUND") {
                 return null;
+            }
             throw err;
         }
     };
@@ -133,6 +156,22 @@ export function createClient(config) {
         getSingle(key, opts = {}) {
             return one(`/v1/delivery/singles/${encodeURIComponent(key)}`, opts, `mapled:${key}`);
         },
+        /** The release the site is reading right now — the latest published
+            one, with the moment it went live — or null before the first
+            publish. Never cached: it's the one short-lived pointer of the
+            delivery API; pass its number as `release` to pin a render. */
+        async getRelease() {
+            const res = await fetch(`${base}/v1/delivery/release`, {
+                headers: { "x-mapled-key": config.key },
+                cache: "no-store",
+            });
+            if (!res.ok)
+                throw await failure(res);
+            const body = (await res.json());
+            if (body.release === null || body.publishedAt === null)
+                return null;
+            return { release: body.release, publishedAt: body.publishedAt };
+        },
     };
 }
 /** Live data (operational collections): the site's backend reads and

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mapled/next",
-  "version": "0.4.0",
-  "description": "Read published Mapled content in a Next.js site — delivery client, ISR tags, and a revalidation webhook handler.",
+  "version": "0.5.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",
   "keywords": [
@@ -47,6 +47,6 @@
   },
   "devDependencies": {
     "typescript": "^5.7.2",
-    "vitest": "^3.0.5"
+    "vitest": "^4.1.11"
   }
 }