@mapled/next 0.1.0 → 0.2.0

package/README.md

@@ -54,6 +54,24 @@ 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.
 
+## Preview drafts
+
+Mount the preview routes:
+
+```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 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.
+
 ## API
 
 - `createClient({ key, apiUrl? })` → `getRecords(collection, opts?)`, `getRecord(collection, id, opts?)`, `getSingle(key, opts?)`

package/dist/index.js

@@ -9,19 +9,40 @@ export class MapledError extends Error {
         this.status = status;
     }
 }
+/** 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. */
+async function draftSession() {
+    try {
+        const mod = await import("next/headers");
+        if (!(await mod.draftMode()).isEnabled)
+            return null;
+        const jar = await mod.cookies();
+        return jar.get("mapled_draft")?.value ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 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.");
     async function call(path, search, opts, cacheTags) {
         const qs = search.toString();
-        const init = {
-            headers: { "x-mapled-key": config.key },
-            next: {
-                revalidate: opts.revalidate ?? 3600,
-                tags: ["mapled", ...cacheTags, ...(opts.tags ?? [])],
-            },
-        };
+        const draft = await draftSession();
+        const init = draft
+            ? {
+                headers: { "x-mapled-key": config.key, "x-mapled-draft": draft },
+                cache: "no-store",
+            }
+            : {
+                headers: { "x-mapled-key": config.key },
+                next: {
+                    revalidate: opts.revalidate ?? 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}).`;

package/dist/server.d.ts

@@ -10,6 +10,14 @@
     then refreshes all "mapled"-tagged fetches instantly. */
 /** Constant-time check of the "x-mapled-signature" header value. */
 export declare function verifySignature(secret: string, body: string, signature: string): Promise<boolean>;
+/** GET handler for the preview route (mount at /api/mapled/preview).
+    Trades the one-time link token from Mapled for a draft session,
+    turns on Next draft mode, and redirects into the site. */
+export declare function createPreviewHandler(options?: {
+    apiUrl?: string;
+}): (req: Request) => Promise<Response>;
+/** GET handler to leave preview (mount at /api/mapled/preview/exit). */
+export declare function createExitPreviewHandler(): (req: Request) => Promise<Response>;
 export declare function createRevalidateHandler(options: {
     secret: string;
     /** Cache tags to refresh — defaults to ["mapled"], which covers every

package/dist/server.js

@@ -27,6 +27,59 @@ export async function verifySignature(secret, body, signature) {
     }
     return diff === 0;
 }
+const DRAFT_COOKIE = "mapled_draft";
+/** Same-app relative path only — preview links can't bounce elsewhere. */
+function safeNext(raw) {
+    return raw && /^\/(?!\/)/.test(raw) ? raw : "/";
+}
+/** GET handler for the preview route (mount at /api/mapled/preview).
+    Trades the one-time link token from Mapled for a draft session,
+    turns on Next draft mode, and redirects into the site. */
+export function createPreviewHandler(options = {}) {
+    const base = (options.apiUrl ?? "https://api.mapled.io").replace(/\/+$/, "");
+    return async function GET(req) {
+        const url = new URL(req.url);
+        const token = url.searchParams.get("token");
+        if (!token)
+            return new Response("Missing preview token.", { status: 400 });
+        const res = await fetch(`${base}/v1/delivery/preview/exchange`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ token }),
+        });
+        if (!res.ok) {
+            return new Response("This preview link has expired. Open it from Mapled again.", {
+                status: 401,
+            });
+        }
+        const { draftToken, expiresAt } = (await res.json());
+        const { draftMode, cookies } = await import("next/headers");
+        (await draftMode()).enable();
+        (await cookies()).set(DRAFT_COOKIE, draftToken, {
+            httpOnly: true,
+            secure: true,
+            sameSite: "lax",
+            path: "/",
+            expires: new Date(expiresAt),
+        });
+        return new Response(null, {
+            status: 307,
+            headers: { location: safeNext(url.searchParams.get("next")) },
+        });
+    };
+}
+/** GET handler to leave preview (mount at /api/mapled/preview/exit). */
+export function createExitPreviewHandler() {
+    return async function GET(req) {
+        const { draftMode, cookies } = await import("next/headers");
+        (await draftMode()).disable();
+        (await cookies()).delete(DRAFT_COOKIE);
+        return new Response(null, {
+            status: 307,
+            headers: { location: safeNext(new URL(req.url).searchParams.get("next")) },
+        });
+    };
+}
 export function createRevalidateHandler(options) {
     if (!options.secret) {
         throw new Error("Mapled: the webhook secret is required.");

package/package.json

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