@mapled/next 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# @mapled/next
+
+Read published [Mapled](https://mapled.io) content in a Next.js site — a delivery client with ISR cache tags, plus a revalidation webhook handler so publishes show up instantly.
+
+Mapled is a hosted headless CMS built for sites created with AI. Your agent (or you) models collections and fills in content; this package is how the site reads what's published.
+
+## Install
+
+```bash
+npm install @mapled/next
+```
+
+Grab the delivery key in Mapled: project → Integrations → **Your site**, and put it in your site's env:
+
+```bash
+MAPLED_KEY=mk_live_…
+```
+
+## Read published content
+
+```ts
+import { createClient } from "@mapled/next";
+
+const mapled = createClient({ key: process.env.MAPLED_KEY! });
+
+// A collection, with filters, sort and pagination
+const { records } = await mapled.getRecords("articles", {
+  filter: { featured: true },
+  sort: "-date",
+  limit: 10,
+});
+
+// One record
+const post = await mapled.getRecord("articles", id);
+
+// A single (e.g. the homepage)
+const home = await mapled.getSingle("homepage");
+```
+
+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.
+
+## Refresh on publish
+
+Mount the webhook handler:
+
+```ts
+// app/api/mapled/revalidate/route.ts
+import { createRevalidateHandler } from "@mapled/next/server";
+
+export const POST = createRevalidateHandler({
+  secret: process.env.MAPLED_WEBHOOK_SECRET!,
+});
+```
+
+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.
+
+## 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`
+- `createRevalidateHandler({ secret, tags? })` — App Router `POST` handler
+- `verifySignature(secret, body, signature)` — if you'd rather build your own handler
+
+The delivery key only reads published, public content — safe to use anywhere.

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+/** 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. */
+export type MapledRecord<T = Record<string, unknown>> = {
+    id: string;
+    data: T;
+};
+export type ListOptions = {
+    /** Equality filters on top-level fields, e.g. { slug: "about" }. */
+    filter?: Record<string, string | number | boolean>;
+    /** 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 declare class MapledError extends Error {
+    status: number;
+    constructor(status: number, message: string);
+}
+export type MapledClient = ReturnType<typeof createClient>;
+export declare function createClient(config: {
+    key: string;
+    apiUrl?: string;
+}): {
+    /** 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>;
+    /** 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>;
+};

package/dist/index.js

@@ -0,0 +1,81 @@
+/** 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. */
+export class MapledError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.name = "MapledError";
+        this.status = status;
+    }
+}
+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 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);
+        }
+        return { status: res.status, body: (await res.json()) };
+    }
+    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 (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));
+            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 = {}) {
+            try {
+                const { body } = await call(`/v1/delivery/collections/${encodeURIComponent(collection)}/records/${encodeURIComponent(id)}`, new URLSearchParams(), opts, [`mapled:${collection}`]);
+                return body.record;
+            }
+            catch (err) {
+                if (err instanceof MapledError && err.status === 404)
+                    return null;
+                throw err;
+            }
+        },
+        /** The record of a single (e.g. "homepage"), or null before publish. */
+        async getSingle(key, opts = {}) {
+            try {
+                const { body } = await call(`/v1/delivery/singles/${encodeURIComponent(key)}`, new URLSearchParams(), opts, [`mapled:${key}`]);
+                return body.record;
+            }
+            catch (err) {
+                if (err instanceof MapledError && err.status === 404)
+                    return null;
+                throw err;
+            }
+        },
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,18 @@
+/** Revalidation webhook handler for Next.js App Router.
+
+    app/api/mapled/revalidate/route.ts:
+      import { createRevalidateHandler } from "@mapled/next/server";
+      export const POST = createRevalidateHandler({
+        secret: process.env.MAPLED_WEBHOOK_SECRET!,
+      });
+
+    Point the project's webhook at /api/mapled/revalidate — every publish
+    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>;
+export declare function createRevalidateHandler(options: {
+    secret: string;
+    /** Cache tags to refresh — defaults to ["mapled"], which covers every
+        client fetch. */
+    tags?: string[];
+}): (req: Request) => Promise<Response>;

package/dist/server.js

@@ -0,0 +1,45 @@
+/** Revalidation webhook handler for Next.js App Router.
+
+    app/api/mapled/revalidate/route.ts:
+      import { createRevalidateHandler } from "@mapled/next/server";
+      export const POST = createRevalidateHandler({
+        secret: process.env.MAPLED_WEBHOOK_SECRET!,
+      });
+
+    Point the project's webhook at /api/mapled/revalidate — every publish
+    then refreshes all "mapled"-tagged fetches instantly. */
+const encoder = new TextEncoder();
+async function hmacHex(secret, body) {
+    const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const mac = await crypto.subtle.sign("HMAC", key, encoder.encode(body));
+    return Array.from(new Uint8Array(mac))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+/** Constant-time check of the "x-mapled-signature" header value. */
+export async function verifySignature(secret, body, signature) {
+    const expected = `sha256=${await hmacHex(secret, body)}`;
+    if (expected.length !== signature.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < expected.length; i++) {
+        diff |= expected.charCodeAt(i) ^ signature.charCodeAt(i);
+    }
+    return diff === 0;
+}
+export function createRevalidateHandler(options) {
+    if (!options.secret) {
+        throw new Error("Mapled: the webhook secret is required.");
+    }
+    return async function POST(req) {
+        const body = await req.text();
+        const signature = req.headers.get("x-mapled-signature");
+        if (!signature || !(await verifySignature(options.secret, body, signature))) {
+            return Response.json({ error: "Invalid signature." }, { status: 401 });
+        }
+        const { revalidateTag } = await import("next/cache");
+        for (const tag of options.tags ?? ["mapled"])
+            revalidateTag(tag);
+        return Response.json({ revalidated: true });
+    };
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@mapled/next",
+  "version": "0.1.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",
+  "keywords": [
+    "mapled",
+    "cms",
+    "headless-cms",
+    "nextjs",
+    "isr",
+    "revalidation"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepare": "npm run build",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "next": ">=14"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.5"
+  }
+}