@mapled/next 0.1.0 → 0.3.0

package/README.md

@@ -54,6 +54,45 @@ 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.
+
+## 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.
+
+```bash
+MAPLED_SERVER_KEY=msk_live_…
+```
+
+```ts
+import { createAppClient } from "@mapled/next";
+
+const db = createAppClient({ serverKey: process.env.MAPLED_SERVER_KEY! });
+
+await db.create("orders", { customer: "Ada Lovelace", total: 120 });
+const { records } = await db.list("orders", { filter: { status: "new" }, sort: "-total" });
+await db.update("orders", id, { ...data, status: "shipped" });
+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.
+
 ## API
 
 - `createClient({ key, apiUrl? })` → `getRecords(collection, opts?)`, `getRecord(collection, id, opts?)`, `getSingle(key, opts?)`

package/dist/index.d.ts

@@ -28,6 +28,19 @@ export declare class MapledError extends Error {
     constructor(status: number, message: string);
 }
 export type MapledClient = ReturnType<typeof createClient>;
+export type MapledAppClient = ReturnType<typeof createAppClient>;
+export type AppRecord<T = Record<string, unknown>> = {
+    id: string;
+    data: T;
+    createdAt: string;
+    updatedAt: string;
+};
+export type AppListOptions = {
+    filter?: Record<string, string | number | boolean>;
+    sort?: string;
+    limit?: number;
+    offset?: number;
+};
 export declare function createClient(config: {
     key: string;
     apiUrl?: string;
@@ -39,3 +52,19 @@ export declare function createClient(config: {
     /** The record of a single (e.g. "homepage"), or null before publish. */
     getSingle<T = Record<string, unknown>>(key: string, opts?: Pick<ListOptions, "revalidate" | "tags">): Promise<MapledRecord<T> | null>;
 };
+/** Live data (operational collections): the site's backend reads and
+    writes records that take effect immediately — no publish involved.
+    Server-side only: the server key must never reach the browser. */
+export declare function createAppClient(config: {
+    serverKey: string;
+    apiUrl?: string;
+}): {
+    list<T = Record<string, unknown>>(collection: string, opts?: AppListOptions): Promise<{
+        records: AppRecord<T>[];
+        total: number;
+    }>;
+    get<T = Record<string, unknown>>(collection: string, id: string): Promise<AppRecord<T> | null>;
+    create<T = Record<string, unknown>>(collection: string, data: T): Promise<AppRecord<T>>;
+    update<T = Record<string, unknown>>(collection: string, id: string, data: T): Promise<AppRecord<T>>;
+    remove(collection: string, id: string): Promise<void>;
+};

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}).`;
@@ -79,3 +100,74 @@ export function createClient(config) {
         },
     };
 }
+/** Live data (operational collections): the site's backend reads and
+    writes records that take effect immediately — no publish involved.
+    Server-side only: the server key must never reach the browser. */
+export function createAppClient(config) {
+    const base = (config.apiUrl ?? "https://api.mapled.io").replace(/\/+$/, "");
+    if (!config.serverKey)
+        throw new Error("Mapled: a server key is required.");
+    async function call(method, path, search, data) {
+        const qs = search?.toString();
+        const res = await fetch(`${base}${path}${qs ? `?${qs}` : ""}`, {
+            method,
+            headers: {
+                "x-mapled-server-key": config.serverKey,
+                ...(data !== undefined ? { "content-type": "application/json" } : {}),
+            },
+            ...(data !== undefined ? { body: JSON.stringify({ data }) } : {}),
+            cache: "no-store",
+        });
+        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);
+        }
+        return (await res.json());
+    }
+    const collectionPath = (c) => `/v1/app/collections/${encodeURIComponent(c)}/records`;
+    return {
+        async list(collection, opts = {}) {
+            const search = new URLSearchParams();
+            for (const [k, v] of Object.entries(opts.filter ?? {})) {
+                search.set(`filter[${k}]`, String(v));
+            }
+            if (opts.sort)
+                search.set("sort", opts.sort);
+            if (opts.limit !== undefined)
+                search.set("limit", String(opts.limit));
+            if (opts.offset !== undefined)
+                search.set("offset", String(opts.offset));
+            return call("GET", collectionPath(collection), search);
+        },
+        async get(collection, id) {
+            try {
+                const body = await call("GET", `${collectionPath(collection)}/${encodeURIComponent(id)}`);
+                return body.record;
+            }
+            catch (err) {
+                if (err instanceof MapledError && err.status === 404)
+                    return null;
+                throw err;
+            }
+        },
+        async create(collection, data) {
+            const body = await call("POST", collectionPath(collection), undefined, data);
+            return body.record;
+        },
+        async update(collection, id, data) {
+            const body = await call("PATCH", `${collectionPath(collection)}/${encodeURIComponent(id)}`, undefined, data);
+            return body.record;
+        },
+        async remove(collection, id) {
+            await call("DELETE", `${collectionPath(collection)}/${encodeURIComponent(id)}`);
+        },
+    };
+}

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.3.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",