@mapled/next 0.2.0 → 0.4.0

package/README.md

@@ -25,20 +25,44 @@ const mapled = createClient({ key: process.env.MAPLED_KEY! });
 
 // A collection, with filters, sort and pagination
 const { records } = await mapled.getRecords("articles", {
-  filter: { featured: true },
+  filter: { featured: true, date: { gte: "2026-01-01" }, title: { contains: "launch" } },
   sort: "-date",
   limit: 10,
 });
 
-// One record
+// One record — by id or by its slug field
 const post = await mapled.getRecord("articles", id);
+const about = await mapled.getRecordBySlug("pages", "about");
 
 // A single (e.g. the homepage)
 const home = await mapled.getSingle("homepage");
+
+// Linked records come along under `expanded` (two levels at most)
+const { records: posts } = await mapled.getRecords("articles", {
+  expand: ["author", "related.author"],
+  fields: ["title", "slug"],
+});
+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.
 
+## 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.
+
+## Images
+
+Image fields hold asset ids. `assetUrl` turns one into a URL — the original, or a resized variant that Mapled makes on the first request and keeps:
+
+```ts
+import { assetUrl } from "@mapled/next";
+
+<img src={assetUrl(post.data.cover, { width: 640 })} alt={post.data.title} />
+// width/height snap to presets (64 … 2560) and never upscale; fit: inside | cover | contain;
+// format: webp (default) | avif | jpeg | png; quality 30 … 100
+```
+
 ## Refresh on publish
 
 Mount the webhook handler:
@@ -72,10 +96,32 @@ 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?)`
-- `opts`: `filter` (equality on top-level fields), `sort` (`"field"` / `"-field"`), `limit` (≤100), `offset`, `revalidate`, `tags`
+- `createClient({ key, apiUrl? })` → `getRecords(collection, opts?)`, `getRecord(collection, id, opts?)`, `getRecordBySlug(collection, slug, opts?)`, `getSingle(key, opts?)`
+- 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
 - `createRevalidateHandler({ secret, tags? })` — App Router `POST` handler
 - `verifySignature(secret, body, signature)` — if you'd rather build your own handler
 

package/dist/index.d.ts

@@ -4,30 +4,81 @@
 export type MapledRecord<T = Record<string, unknown>> = {
     id: string;
     data: T;
+    /** Linked records asked for with `expand`: one record (or null) for a
+        one-to-one field, an array for one-to-many. */
+    expanded?: Record<string, MapledRecord | MapledRecord[] | null>;
 };
-export type ListOptions = {
-    /** Equality filters on top-level fields, e.g. { slug: "about" }. */
-    filter?: Record<string, string | number | boolean>;
+/** A filter value: plain equality, or operators by field type —
+    text: eq/ne/in/contains; number and date: eq/ne/lt/lte/gt/gte/in;
+    boolean: eq/ne; image and relation ids: eq/ne/in. */
+export type FilterValue = string | number | boolean | {
+    eq?: string | number | boolean;
+    ne?: string | number | boolean;
+    lt?: string | number;
+    lte?: string | number;
+    gt?: string | number;
+    gte?: string | number;
+    in?: (string | number)[];
+    contains?: string;
+};
+export type ReadOptions = {
+    /** Relation fields to attach under `expanded`, up to two levels:
+        ["author", "related.author"]. */
+    expand?: string[];
+    /** Only these data keys come back. */
+    fields?: string[];
+    /** ISR window in seconds (default 3600 — the webhook keeps you fresh). */
+    revalidate?: number | false;
+    /** Extra cache tags on top of "mapled" and "mapled:<collection>". */
+    tags?: string[];
+};
+export type ListOptions = ReadOptions & {
+    /** Filters on top-level fields, ANDed: { slug: "about", price: { gte: 10 } }. */
+    filter?: Record<string, FilterValue>;
     /** Field key, or "-field" for descending. */
     sort?: string;
     /** 1..100, default 100. */
     limit?: number;
     offset?: number;
-    /** ISR window in seconds (default 3600 — the webhook keeps you fresh). */
-    revalidate?: number | false;
-    /** Extra cache tags on top of "mapled" and "mapled:<collection>". */
-    tags?: string[];
 };
 export type ListResult<T = Record<string, unknown>> = {
     records: MapledRecord<T>[];
     total: number;
     release: number;
 };
+export type ImageOptions = {
+    /** Snapped up to the nearest preset (64 … 2560); never upscaled past the source. */
+    width?: number;
+    height?: number;
+    /** inside (default) keeps the whole image within the box; cover fills it; contain pads it. */
+    fit?: "cover" | "contain" | "inside";
+    /** webp (default), avif, jpeg or png. */
+    format?: "webp" | "avif" | "jpeg" | "png";
+    /** 30 … 100, in steps of 10 (default 80). */
+    quality?: number;
+    apiUrl?: string;
+};
+/** 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 declare function assetUrl(id: string, opts?: ImageOptions): string;
 export declare class MapledError extends Error {
     status: number;
     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;
@@ -35,7 +86,25 @@ export declare function createClient(config: {
     /** Published records of a collection, with filters/sort/pagination. */
     getRecords<T = Record<string, unknown>>(collection: string, opts?: ListOptions): Promise<ListResult<T>>;
     /** One published record by id, or null when it isn't in the release. */
-    getRecord<T = Record<string, unknown>>(collection: string, id: string, opts?: Pick<ListOptions, "revalidate" | "tags">): Promise<MapledRecord<T> | null>;
+    getRecord<T = Record<string, unknown>>(collection: string, id: string, opts?: ReadOptions): Promise<MapledRecord<T> | null>;
+    /** One published record by the collection's slug field, or null. */
+    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?: Pick<ListOptions, "revalidate" | "tags">): Promise<MapledRecord<T> | null>;
+    getSingle<T = Record<string, unknown>>(key: string, opts?: ReadOptions): 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

@@ -1,6 +1,24 @@
 /** 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. */
+/** 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 = {}) {
+    const base = (opts.apiUrl ?? "https://api.mapled.io").replace(/\/+$/, "");
+    const search = new URLSearchParams();
+    if (opts.width)
+        search.set("w", String(opts.width));
+    if (opts.height)
+        search.set("h", String(opts.height));
+    if (opts.fit)
+        search.set("fit", opts.fit);
+    if (opts.format)
+        search.set("fmt", opts.format);
+    if (opts.quality)
+        search.set("q", String(opts.quality));
+    const qs = search.toString();
+    return `${base}/files/${encodeURIComponent(id)}${qs ? `?${qs}` : ""}`;
+}
 export class MapledError extends Error {
     status;
     constructor(status, message) {
@@ -58,12 +76,40 @@ export function createClient(config) {
         }
         return { status: res.status, body: (await res.json()) };
     }
+    /** expand / fields on every read. */
+    const readParams = (search, opts) => {
+        if (opts.expand?.length)
+            search.set("expand", opts.expand.join(","));
+        if (opts.fields?.length)
+            search.set("fields", opts.fields.join(","));
+        return search;
+    };
+    const one = async (path, opts, tag) => {
+        try {
+            const { body } = await call(path, readParams(new URLSearchParams(), opts), opts, [tag]);
+            return body.record;
+        }
+        catch (err) {
+            if (err instanceof MapledError && err.status === 404)
+                return null;
+            throw err;
+        }
+    };
     return {
         /** Published records of a collection, with filters/sort/pagination. */
         async getRecords(collection, opts = {}) {
             const search = new URLSearchParams();
             for (const [k, v] of Object.entries(opts.filter ?? {})) {
-                search.set(`filter[${k}]`, String(v));
+                if (v !== null && typeof v === "object") {
+                    for (const [op, ov] of Object.entries(v)) {
+                        if (ov === undefined)
+                            continue;
+                        search.set(`filter[${k}][${op}]`, Array.isArray(ov) ? ov.join(",") : String(ov));
+                    }
+                }
+                else {
+                    search.set(`filter[${k}]`, String(v));
+                }
             }
             if (opts.sort)
                 search.set("sort", opts.sort);
@@ -71,25 +117,74 @@ export function createClient(config) {
                 search.set("limit", String(opts.limit));
             if (opts.offset !== undefined)
                 search.set("offset", String(opts.offset));
+            readParams(search, opts);
             const { body } = await call(`/v1/delivery/collections/${encodeURIComponent(collection)}/records`, search, opts, [`mapled:${collection}`]);
             return body;
         },
         /** One published record by id, or null when it isn't in the release. */
-        async getRecord(collection, id, opts = {}) {
+        getRecord(collection, id, opts = {}) {
+            return one(`/v1/delivery/collections/${encodeURIComponent(collection)}/records/${encodeURIComponent(id)}`, opts, `mapled:${collection}`);
+        },
+        /** One published record by the collection's slug field, or null. */
+        getRecordBySlug(collection, slug, opts = {}) {
+            return one(`/v1/delivery/collections/${encodeURIComponent(collection)}/records/by-slug/${encodeURIComponent(slug)}`, opts, `mapled:${collection}`);
+        },
+        /** The record of a single (e.g. "homepage"), or null before publish. */
+        getSingle(key, opts = {}) {
+            return one(`/v1/delivery/singles/${encodeURIComponent(key)}`, opts, `mapled:${key}`);
+        },
+    };
+}
+/** 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 { body } = await call(`/v1/delivery/collections/${encodeURIComponent(collection)}/records/${encodeURIComponent(id)}`, new URLSearchParams(), opts, [`mapled:${collection}`]);
-                return body.record;
+                const parsed = (await res.json());
+                if (parsed.error?.message)
+                    message = parsed.error.message;
             }
-            catch (err) {
-                if (err instanceof MapledError && err.status === 404)
-                    return null;
-                throw err;
+            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);
         },
-        /** The record of a single (e.g. "homepage"), or null before publish. */
-        async getSingle(key, opts = {}) {
+        async get(collection, id) {
             try {
-                const { body } = await call(`/v1/delivery/singles/${encodeURIComponent(key)}`, new URLSearchParams(), opts, [`mapled:${key}`]);
+                const body = await call("GET", `${collectionPath(collection)}/${encodeURIComponent(id)}`);
                 return body.record;
             }
             catch (err) {
@@ -98,5 +193,16 @@ export function createClient(config) {
                 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

@@ -15,6 +15,7 @@ export declare function verifySignature(secret: string, body: string, signature:
     turns on Next draft mode, and redirects into the site. */
 export declare function createPreviewHandler(options?: {
     apiUrl?: string;
+    appUrl?: string;
 }): (req: Request) => Promise<Response>;
 /** GET handler to leave preview (mount at /api/mapled/preview/exit). */
 export declare function createExitPreviewHandler(): (req: Request) => Promise<Response>;

package/dist/server.js

@@ -37,6 +37,7 @@ function safeNext(raw) {
     turns on Next draft mode, and redirects into the site. */
 export function createPreviewHandler(options = {}) {
     const base = (options.apiUrl ?? "https://api.mapled.io").replace(/\/+$/, "");
+    const app = (options.appUrl ?? "https://app.mapled.io").replace(/\/+$/, "");
     return async function GET(req) {
         const url = new URL(req.url);
         const token = url.searchParams.get("token");
@@ -48,9 +49,11 @@ export function createPreviewHandler(options = {}) {
             body: JSON.stringify({ token }),
         });
         if (!res.ok) {
-            return new Response("This preview link has expired. Open it from Mapled again.", {
-                status: 401,
-            });
+            // Spent or expired link (S-35): back to Mapled to start a new preview.
+            const payload = (await res.json().catch(() => null));
+            const projectId = payload?.error?.projectId;
+            const target = `${app}/preview/expired${projectId ? `?project=${encodeURIComponent(projectId)}` : ""}`;
+            return new Response(null, { status: 307, headers: { location: target } });
         }
         const { draftToken, expiresAt } = (await res.json());
         const { draftMode, cookies } = await import("next/headers");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapled/next",
-  "version": "0.2.0",
+  "version": "0.4.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",