@mapled/next 0.2.0 → 0.3.0

package/README.md

@@ -72,6 +72,27 @@ 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

@@ -100,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/package.json

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