@contentai/next 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Digiboffins
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,229 @@
+# @contentai/next
+
+Connect any Next.js website (App Router, Next.js 14.2+) to ContentAI: read
+published posts from the Delivery API and refresh pages when ContentAI sends a
+signed event. No database is needed on the website.
+
+You need a ContentAI account; the values below come from your ContentAI.
+
+## Install
+
+```bash
+npm install @contentai/next
+```
+
+## Configure
+
+Create a Next.js connection in ContentAI (Connections → Next.js). It shows these
+values once:
+
+```bash
+# .env.local on the website — server-side only, never NEXT_PUBLIC_
+CONTENTAI_API_URL=https://your-contentai-url
+CONTENTAI_SITE_KEY=cai_site_…
+CONTENTAI_WEBHOOK_SECRET=whsec_…
+```
+
+## Use
+
+```ts
+// lib/contentai.ts
+import "server-only";
+import { createClient } from "@contentai/next";
+
+export const contentai = createClient({
+  apiUrl: process.env.CONTENTAI_API_URL!,
+  siteKey: process.env.CONTENTAI_SITE_KEY!,
+  revalidate: 600, // fallback refresh, in seconds
+  timeoutMs: 5000, // give up on an unreachable ContentAI instead of hanging the page
+});
+```
+
+```tsx
+// app/blog/[slug]/page.tsx
+import { toMetadata } from "@contentai/next";
+import { contentai } from "@/lib/contentai";
+
+export async function generateMetadata({ params }) {
+  const result = await contentai.posts.get((await params).slug);
+  return result?.type === "post" ? toMetadata(result.post) : {};
+}
+
+export default async function Page({ params }) {
+  // Returns the post, calls notFound(), or permanently redirects a renamed slug.
+  const post = await contentai.posts.resolve((await params).slug, (s) => `/blog/${s}`);
+  return <article dangerouslySetInnerHTML={{ __html: post.html }} />;
+}
+```
+
+Create the webhook route with one command, run in your website's folder:
+
+```bash
+npx @contentai/next init
+```
+
+It writes `app/api/contentai/webhook/route.ts` (or `src/app/…`, `route.js` without
+TypeScript), never overwrites an existing route unless you pass `--force`, and
+accepts `--path` for a different route path. The minimal equivalent by hand:
+
+```ts
+// app/api/contentai/webhook/route.ts
+import { createWebhookHandler } from "@contentai/next/webhook";
+
+export const POST = createWebhookHandler({
+  secret: process.env.CONTENTAI_WEBHOOK_SECRET!,
+});
+```
+
+```ts
+// app/sitemap.ts
+import { toSitemap } from "@contentai/next";
+import { contentai } from "@/lib/contentai";
+
+export default async function sitemap() {
+  return toSitemap(await contentai.sitemap());
+}
+```
+
+If posts include images, allow ContentAI's media host in `next.config`
+`images.remotePatterns`.
+
+## Connect your own website
+
+Requires Next.js 14.2+ with the App Router, Node.js 18.18+, and a ContentAI
+account.
+
+1. **Sign in to ContentAI** at your ContentAI URL.
+2. **Install the SDK** in your website: `npm install @contentai/next`.
+3. **Create the webhook route:** `npx @contentai/next init` (see Webhook setup).
+4. **Create the connection** in ContentAI (Connections → Next.js):
+   - Website URL: your site, e.g. `http://localhost:3001`.
+   - Post URL pattern: must match your blog route, e.g. `/blog/{slug}` for
+     `app/blog/[slug]/page.tsx`.
+   - Delivery: Webhook with `{your site}/api/contentai/webhook`, or None to
+     rely on the `revalidate` interval.
+5. **Copy the credentials** ContentAI shows once into `.env.local` (see
+   Configure), then restart the dev server.
+6. **Add the files** from Use: `lib/contentai.ts`, a post list and post page
+   under `app/blog/`, and optionally `app/sitemap.ts`.
+7. **Test:** click Test Connection in ContentAI, publish an article, and open
+   your blog page.
+
+**Deployed websites:**
+
+- Set the three variables in the host's environment variables (e.g. Vercel →
+  Settings → Environment Variables), then redeploy.
+- The webhook URL must be your site's public URL, so ContentAI can reach it.
+- Allow ContentAI's media host in `images.remotePatterns` so post images load.
+
+### Webhook setup
+
+**1. Create the webhook route.** In your website's folder:
+
+```bash
+npx @contentai/next init
+```
+
+- Creates `app/api/contentai/webhook/route.ts`. Uses `src/app/` if your project
+  has it, and `route.js` without TypeScript.
+- Never replaces an existing route; `--force` does. `--path hooks/cms` puts the
+  route at a different path.
+- Next.js only serves routes that exist as files in your `app/` folder, so a
+  package cannot add one by itself: the command writes the file once, and it
+  is then part of your website.
+- The route answers 503 until `CONTENTAI_WEBHOOK_SECRET` is set.
+
+**2. Work out the webhook URL.** Your website's URL plus the route path:
+`http://localhost:3001/api/contentai/webhook` locally, or
+`https://yoursite.com/api/contentai/webhook` when deployed.
+
+**3. Enter it in ContentAI.** Connections → Next.js → Delivery: **Webhook**.
+
+- The Webhook URL field suggests `{Website URL}/api/contentai/webhook`. When
+  creating the connection, leave it blank to use that; type a URL only if you
+  used `--path`.
+- In production ContentAI only accepts public `https` URLs; `http` and
+  localhost are allowed in development.
+- To change it later, open the connection, edit the URL and click **Save
+  Settings**.
+
+**4. Add the webhook secret.** ContentAI generates `CONTENTAI_WEBHOOK_SECRET`
+when the connection is created and shows it **only once**, together with the
+site key.
+
+- Copy it into `.env.local` (or the host's environment variables), never with
+  `NEXT_PUBLIC_`, then restart or redeploy.
+- Lost it? Open the connection and click **Rotate webhook secret**. The new
+  secret is shown once, and for 7 days events are signed with both the old and
+  new secret, so the website can switch without missing events.
+
+**5. Click Test Connection.** It appears once the connection is created.
+
+- **Webhook:** ContentAI sends a signed `connection.ping` to the URL and waits
+  up to 10 seconds. Success means the route exists, is reachable and has the
+  right secret; the connection becomes **Active**.
+- **Deploy hook:** checks the URL is allowed without calling it (calling it
+  would start a build).
+- **None:** always succeeds.
+- It does **not** check the site key. A wrong `CONTENTAI_SITE_KEY` passes the
+  test and shows up later as a 401 when the website fetches posts.
+
+| Test Connection says | Usually means | Fix |
+|---|---|---|
+| `answered HTTP 503` | Secret not set on the website | Add `CONTENTAI_WEBHOOK_SECRET`, restart |
+| `answered HTTP 401` | Wrong secret | Copy the secret again, or rotate it |
+| `answered HTTP 404` | No route at that URL | Run `npx @contentai/next init`; check the URL and `--path` |
+| `answered HTTP 3xx` | The URL redirects (e.g. http → https) | Enter the final URL; redirects are not followed |
+| `Could not reach the webhook` / `Timed out after 10s` | Website not running or not reachable from ContentAI | Start the site; ContentAI cannot reach a website on your own `localhost` |
+
+Every attempt is listed under **Recent deliveries** in the connection. If the
+website answers `410 Gone`, ContentAI stops delivering until the webhook URL or
+delivery mode is saved again.
+
+**Not built yet:** a command for the other files (`lib/contentai.ts`, blog
+pages), a site key check in Test Connection, and an automatic test when the
+connection is first created.
+
+## API
+
+| Export | Purpose |
+|---|---|
+| `createClient(options)` | `posts.list(params)`, `posts.get(slug)`, `posts.resolve(slug, pathFor)`, `categories.list()`, `tags.list()`, `sitemap()`, `site()` |
+| `createWebhookHandler(options)` | A `POST` route handler: verifies the signature, ignores replays, revalidates cache tags, then calls `onEvent` |
+| `verifyWebhook(headers, rawBody, { secret })` | Verification only, for custom handlers |
+| `toMetadata(post)` / `toSitemap(entries)` | Next.js `Metadata` and sitemap entries |
+| `TAGS`, `tagsForEvent(event)` | The cache tags the client and webhook handler use |
+| `ContentAIError` | Thrown for API errors; `code` is ContentAI's error code |
+
+## Keeping your own copy of posts
+
+Websites with a database can copy posts in `onEvent`:
+
+```ts
+export const POST = createWebhookHandler({
+  secret: process.env.CONTENTAI_WEBHOOK_SECRET!,
+  onEvent: async (event) => {
+    if (event.type === "post.published" || event.type === "post.updated") {
+      // Upsert by event.data.post.id, only when event.data.post.version is newer.
+    }
+    if (event.type === "post.unpublished" || event.type === "post.deleted") {
+      // Remove by event.data.id, only when event.data.version is newer.
+    }
+  },
+});
+```
+
+Retries can arrive out of order; always compare `version`.
+
+## Notes
+
+- **Multiple server instances (self-hosted):** Next.js's built-in cache is
+  per instance, so only the instance that receives the webhook refreshes at
+  once; others refresh on the `revalidate` interval. Configure a shared
+  `cacheHandler` if every instance must update immediately. Vercel handles this.
+- **Local development on WSL2:** WSL2 periodically steps the system clock, and
+  Next.js 15 compares cache timestamps taken from two different clocks, so a
+  page cached within the last few seconds before an event can stay stale until
+  the `revalidate` interval. This does not happen on normal servers.
+- **Static exports** (`output: 'export'`) cannot receive webhooks; use the
+  deploy hook delivery mode in ContentAI instead.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import { DEFAULT_WEBHOOK_PATH, init, InitError } from "./init.js";
+const HELP = `Usage: npx @contentai/next init [--path <route path>] [--force]
+
+Creates the ContentAI webhook route in your Next.js website.
+
+  --path   Route path under app/ (default ${DEFAULT_WEBHOOK_PATH})
+  --force  Replace the route file if it already exists
+`;
+function main(argv) {
+    const [command, ...rest] = argv;
+    if (!command || command === "--help" || command === "-h") {
+        console.log(HELP);
+        return command ? 0 : 1;
+    }
+    if (command !== "init") {
+        console.error(`Unknown command: ${command}\n\n${HELP}`);
+        return 1;
+    }
+    let path;
+    let force = false;
+    for (let i = 0; i < rest.length; i++) {
+        if (rest[i] === "--force")
+            force = true;
+        else if (rest[i] === "--path" && rest[i + 1])
+            path = rest[++i];
+        else {
+            console.error(`Unknown option: ${rest[i]}\n\n${HELP}`);
+            return 1;
+        }
+    }
+    try {
+        const result = init({ cwd: process.cwd(), path, force });
+        if (result.status === "exists") {
+            console.log(`The webhook route already exists: ${result.file}\nNothing was changed. Use --force to replace it.`);
+        }
+        else {
+            console.log(`${result.status === "created" ? "Created" : "Replaced"} ${result.file}
+
+Next steps:
+  1. Put CONTENTAI_WEBHOOK_SECRET (shown by ContentAI) in .env.local, then restart the dev server.
+  2. In ContentAI, set Delivery to Webhook with the URL:
+       {your website URL}${result.urlPath}
+  3. Click Test Connection.`);
+        }
+        return 0;
+    }
+    catch (error) {
+        if (error instanceof InitError) {
+            console.error(error.message);
+            return 1;
+        }
+        throw error;
+    }
+}
+process.exitCode = main(process.argv.slice(2));

package/dist/client.d.ts

@@ -0,0 +1,49 @@
+import type { DeliveryErrorCode, ListPostsParams, Post, PostList, PostLookup, SiteInfo, SitemapEntry, TermWithCount } from "./types.js";
+export interface ClientOptions {
+    /** ContentAI's base URL, e.g. process.env.CONTENTAI_API_URL. */
+    apiUrl: string;
+    /** Server-only. Never expose it through a NEXT_PUBLIC_ variable. */
+    siteKey: string;
+    /**
+     * Seconds before cached data is refetched even without an event. This is
+     * what keeps a website correct when an event is lost. Default 600.
+     */
+    revalidate?: number;
+    /** For tests or custom runtimes. Defaults to the global fetch. */
+    fetch?: typeof fetch;
+    /** Retries for 429, 5xx and connection failures. Default 2. */
+    maxRetries?: number;
+    /**
+     * Per-request time limit in milliseconds. Default 5000. A request that
+     * times out is not retried: an unreachable ContentAI must not hold a page
+     * render for the network's own connect timeout, several times over.
+     */
+    timeoutMs?: number;
+}
+export declare class ContentAIError extends Error {
+    readonly status: number;
+    readonly code: DeliveryErrorCode | "network_error";
+    constructor(status: number, code: DeliveryErrorCode | "network_error", message: string);
+}
+export declare function createClient(options: ClientOptions): {
+    posts: {
+        list: (params?: ListPostsParams) => Promise<PostList>;
+        /** A post, a redirect for a renamed slug, or null. */
+        get: (slug: string) => Promise<PostLookup | null>;
+        /**
+         * For a post page: returns the post, calls notFound() when there is
+         * none, and permanentRedirect() when the slug was renamed. `pathFor`
+         * builds the new URL path; it defaults to /blog/{slug}.
+         */
+        resolve(slug: string, pathFor?: (slug: string) => string): Promise<Post>;
+    };
+    categories: {
+        list: () => Promise<TermWithCount[]>;
+    };
+    tags: {
+        list: () => Promise<TermWithCount[]>;
+    };
+    sitemap: () => Promise<SitemapEntry[]>;
+    site: () => Promise<SiteInfo>;
+};
+export type ContentAIClient = ReturnType<typeof createClient>;

package/dist/client.js

@@ -0,0 +1,136 @@
+import { TAGS } from "./tags.js";
+export class ContentAIError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "ContentAIError";
+    }
+}
+const MAX_RETRY_WAIT_MS = 10_000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function createClient(options) {
+    if (typeof window !== "undefined") {
+        throw new Error("@contentai/next: createClient must only run on the server; the site key is secret.");
+    }
+    if (!options.apiUrl)
+        throw new Error("@contentai/next: apiUrl is required (CONTENTAI_API_URL)");
+    if (!options.siteKey)
+        throw new Error("@contentai/next: siteKey is required (CONTENTAI_SITE_KEY)");
+    const base = `${options.apiUrl.replace(/\/+$/, "")}/api/delivery/v1`;
+    const revalidate = options.revalidate ?? 600;
+    const fetchImpl = options.fetch ?? fetch;
+    const maxRetries = options.maxRetries ?? 2;
+    const timeoutMs = options.timeoutMs ?? 5000;
+    async function request(path, tags, allowNotFound = false) {
+        const init = {
+            headers: { Authorization: `Bearer ${options.siteKey}`, Accept: "application/json" },
+            next: { revalidate, tags: [TAGS.all, ...tags] },
+        };
+        for (let attempt = 0;; attempt++) {
+            // A referenced timer (not AbortSignal.timeout, whose timer does not keep
+            // the process alive), cleared once the body has been read.
+            const controller = new AbortController();
+            let timedOut = false;
+            const timer = setTimeout(() => {
+                timedOut = true;
+                controller.abort();
+            }, timeoutMs);
+            let waitBeforeRetry = null;
+            try {
+                let response;
+                try {
+                    response = await fetchImpl(`${base}${path}`, { ...init, signal: controller.signal });
+                }
+                catch (error) {
+                    if (timedOut) {
+                        throw new ContentAIError(0, "network_error", `ContentAI did not respond within ${timeoutMs}ms`);
+                    }
+                    if (attempt < maxRetries) {
+                        waitBeforeRetry = 500 * 2 ** attempt;
+                        continue;
+                    }
+                    throw new ContentAIError(0, "network_error", `Could not reach ContentAI: ${error.message}`);
+                }
+                if (response.ok)
+                    return (await response.json());
+                if (response.status === 404 && allowNotFound)
+                    return null;
+                const retryable = response.status === 429 || response.status >= 500;
+                if (retryable && attempt < maxRetries) {
+                    const retryAfter = Number(response.headers.get("retry-after"));
+                    waitBeforeRetry = Math.min(Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : 500 * 2 ** attempt, MAX_RETRY_WAIT_MS);
+                    continue;
+                }
+                let code = response.status >= 500 ? "server_error" : "invalid_request";
+                let message = `ContentAI responded ${response.status}`;
+                try {
+                    const body = (await response.json());
+                    if (body.error?.code)
+                        code = body.error.code;
+                    if (body.error?.message)
+                        message = body.error.message;
+                }
+                catch {
+                    // Not the contract's error body; keep the generic message.
+                }
+                throw new ContentAIError(response.status, code, message);
+            }
+            catch (error) {
+                // A timeout while reading the body surfaces here as an abort.
+                if (timedOut && !(error instanceof ContentAIError)) {
+                    throw new ContentAIError(0, "network_error", `ContentAI did not respond within ${timeoutMs}ms`);
+                }
+                throw error;
+            }
+            finally {
+                clearTimeout(timer);
+                if (waitBeforeRetry !== null)
+                    await sleep(waitBeforeRetry);
+            }
+        }
+    }
+    function query(params) {
+        const search = new URLSearchParams();
+        for (const [key, value] of Object.entries(params)) {
+            if (value !== undefined && value !== "")
+                search.set(key, String(value));
+        }
+        const text = search.toString();
+        return text ? `?${text}` : "";
+    }
+    return {
+        posts: {
+            list: (params = {}) => request(`/posts${query({ ...params })}`, [TAGS.posts]),
+            /** A post, a redirect for a renamed slug, or null. */
+            get: (slug) => request(`/posts/${encodeURIComponent(slug)}`, [TAGS.slug(slug)], true),
+            /**
+             * For a post page: returns the post, calls notFound() when there is
+             * none, and permanentRedirect() when the slug was renamed. `pathFor`
+             * builds the new URL path; it defaults to /blog/{slug}.
+             */
+            async resolve(slug, pathFor = (s) => `/blog/${s}`) {
+                const result = await request(`/posts/${encodeURIComponent(slug)}`, [TAGS.slug(slug)], true);
+                const navigation = await import("next/navigation");
+                // Both throw Next's control-flow errors; they never return.
+                if (!result)
+                    return navigation.notFound();
+                if (result.type === "redirect")
+                    return navigation.permanentRedirect(pathFor(result.slug));
+                return result.post;
+            },
+        },
+        categories: {
+            list: () => request("/categories", [TAGS.posts]).then((r) => r.data),
+        },
+        tags: {
+            list: () => request("/tags", [TAGS.posts]).then((r) => r.data),
+        },
+        sitemap: () => request("/sitemap", [TAGS.posts]).then((r) => r.data),
+        site: () => request("/site", []),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createClient, ContentAIError } from "./client.js";
+export type { ClientOptions, ContentAIClient } from "./client.js";
+export { toMetadata, toSitemap } from "./metadata.js";
+export { TAGS, tagsForEvent } from "./tags.js";
+export type * from "./types.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createClient, ContentAIError } from "./client.js";
+export { toMetadata, toSitemap } from "./metadata.js";
+export { TAGS, tagsForEvent } from "./tags.js";

package/dist/init.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `npx @contentai/next init`: writes the webhook route into a Next.js website, so
+ * nobody has to copy it by hand. Next.js only serves routes that exist as
+ * files in the website's own app/ folder; a package cannot add one, so the
+ * file is generated once and then belongs to the website.
+ */
+export declare const DEFAULT_WEBHOOK_PATH = "api/contentai/webhook";
+export declare class InitError extends Error {
+    constructor(message: string);
+}
+export interface InitOptions {
+    /** The website's root folder, where its package.json is. */
+    cwd: string;
+    /** Route path under app/. Default api/contentai/webhook. */
+    path?: string;
+    /** Replace an existing route file. */
+    force?: boolean;
+}
+export interface InitResult {
+    status: "created" | "overwritten" | "exists";
+    /** The route file, relative to cwd. */
+    file: string;
+    /** The URL path the route answers, e.g. /api/contentai/webhook. */
+    urlPath: string;
+}
+export declare function init(options: InitOptions): InitResult;

package/dist/init.js

@@ -0,0 +1,84 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+/**
+ * `npx @contentai/next init`: writes the webhook route into a Next.js website, so
+ * nobody has to copy it by hand. Next.js only serves routes that exist as
+ * files in the website's own app/ folder; a package cannot add one, so the
+ * file is generated once and then belongs to the website.
+ */
+export const DEFAULT_WEBHOOK_PATH = "api/contentai/webhook";
+export class InitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InitError";
+    }
+}
+const ROUTE_FILES = ["route.ts", "route.js", "route.tsx", "route.jsx", "route.mjs"];
+function routeSource(typescript) {
+    const handlerType = typescript ? ": Request" : "";
+    return `// POST: signed events from ContentAI (created by \`npx @contentai/next init\`).
+// Verifies each event with CONTENTAI_WEBHOOK_SECRET and refreshes the
+// affected pages. Enter this route's full URL as the Webhook URL in ContentAI.
+import { createWebhookHandler } from "@contentai/next/webhook";
+
+const secret = process.env.CONTENTAI_WEBHOOK_SECRET;
+
+const handler = secret ? createWebhookHandler({ secret }) : null;
+
+export async function POST(request${handlerType}) {
+  if (!handler) {
+    // Without the secret no event can be verified; say so instead of 401.
+    return Response.json({ error: "CONTENTAI_WEBHOOK_SECRET is not configured" }, { status: 503 });
+  }
+  return handler(request);
+}
+`;
+}
+function normalizePath(raw) {
+    const segments = raw.split(/[\\/]+/).filter(Boolean);
+    if (segments.length === 0 || segments.some((segment) => segment === "." || segment === "..")) {
+        throw new InitError(`Invalid route path: ${raw}`);
+    }
+    return segments.join("/");
+}
+function readPackageJson(cwd) {
+    const file = join(cwd, "package.json");
+    if (!existsSync(file)) {
+        throw new InitError("No package.json here. Run this command in your Next.js website's folder.");
+    }
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        throw new InitError("package.json could not be read.");
+    }
+}
+function findAppDir(cwd) {
+    for (const candidate of ["src/app", "app"]) {
+        if (existsSync(join(cwd, candidate)))
+            return join(cwd, candidate);
+    }
+    if (existsSync(join(cwd, "pages")) || existsSync(join(cwd, "src/pages"))) {
+        throw new InitError("Only a pages/ folder was found. The ContentAI webhook needs the App Router (an app/ folder).");
+    }
+    throw new InitError("No app/ or src/app/ folder found. The ContentAI webhook needs the App Router.");
+}
+export function init(options) {
+    const { cwd, force = false } = options;
+    const pkg = readPackageJson(cwd);
+    if (!pkg.dependencies?.next && !pkg.devDependencies?.next) {
+        throw new InitError("This package.json does not list next. Run this command in your Next.js website's folder.");
+    }
+    const routePath = normalizePath(options.path ?? DEFAULT_WEBHOOK_PATH);
+    const routeDir = join(findAppDir(cwd), ...routePath.split("/"));
+    const urlPath = `/${routePath}`;
+    const existing = ROUTE_FILES.map((name) => join(routeDir, name)).find((file) => existsSync(file));
+    if (existing && !force) {
+        return { status: "exists", file: relative(cwd, existing), urlPath };
+    }
+    const typescript = existsSync(join(cwd, "tsconfig.json"));
+    const file = existing ?? join(routeDir, typescript ? "route.ts" : "route.js");
+    mkdirSync(routeDir, { recursive: true });
+    writeFileSync(file, routeSource(typescript));
+    return { status: existing ? "overwritten" : "created", file: relative(cwd, file), urlPath };
+}

package/dist/metadata.d.ts

@@ -0,0 +1,6 @@
+import type { Metadata, MetadataRoute } from "next";
+import type { Post, SitemapEntry } from "./types.js";
+/** generateMetadata() output for a post page, from the post's SEO fields. */
+export declare function toMetadata(post: Post): Metadata;
+/** app/sitemap.ts entries from client.sitemap(). */
+export declare function toSitemap(entries: SitemapEntry[]): MetadataRoute.Sitemap;

package/dist/metadata.js

@@ -0,0 +1,25 @@
+/** generateMetadata() output for a post page, from the post's SEO fields. */
+export function toMetadata(post) {
+    const image = post.seo.ogImage;
+    return {
+        title: post.seo.title,
+        description: post.seo.description,
+        keywords: post.seo.keywords.length ? post.seo.keywords : undefined,
+        alternates: { canonical: post.seo.canonicalUrl },
+        robots: post.seo.noindex ? { index: false, follow: true } : undefined,
+        openGraph: {
+            type: "article",
+            title: post.seo.title,
+            description: post.seo.description,
+            url: post.seo.canonicalUrl,
+            publishedTime: post.publishedAt,
+            modifiedTime: post.updatedAt,
+            tags: post.tags.map((t) => t.name),
+            images: image ? [{ url: image.url, width: image.width, height: image.height, alt: image.alt }] : undefined,
+        },
+    };
+}
+/** app/sitemap.ts entries from client.sitemap(). */
+export function toSitemap(entries) {
+    return entries.map((entry) => ({ url: entry.url, lastModified: entry.updatedAt }));
+}

package/dist/tags.d.ts

@@ -0,0 +1,12 @@
+import type { ContentAIEvent } from "./types.js";
+/**
+ * Cache tags, per the contract §7. Every Delivery API fetch is tagged, and
+ * events revalidate exactly the tags whose data they change.
+ */
+export declare const TAGS: {
+    readonly all: "contentai";
+    readonly posts: "contentai:posts";
+    readonly post: (id: string) => string;
+    readonly slug: (slug: string) => string;
+};
+export declare function tagsForEvent(event: ContentAIEvent): string[];

package/dist/tags.js

@@ -0,0 +1,28 @@
+/**
+ * Cache tags, per the contract §7. Every Delivery API fetch is tagged, and
+ * events revalidate exactly the tags whose data they change.
+ */
+export const TAGS = {
+    all: "contentai",
+    posts: "contentai:posts",
+    post: (id) => `contentai:post:${id}`,
+    slug: (slug) => `contentai:slug:${slug}`,
+};
+export function tagsForEvent(event) {
+    switch (event.type) {
+        case "post.published":
+            return [TAGS.posts, TAGS.slug(event.data.post.slug)];
+        case "post.updated":
+            return [
+                TAGS.posts,
+                TAGS.post(event.data.post.id),
+                TAGS.slug(event.data.post.slug),
+                ...event.data.previousSlugs.map(TAGS.slug),
+            ];
+        case "post.unpublished":
+        case "post.deleted":
+            return [TAGS.posts, TAGS.post(event.data.id), TAGS.slug(event.data.slug)];
+        default:
+            return [];
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The ContentAI Delivery API contract, v1.
+ * Source of truth: docs/NEXTJS_CONTRACT.md in the ContentAI repository.
+ */
+export interface Image {
+    url: string;
+    width: number;
+    height: number;
+    alt: string;
+}
+export interface Term {
+    name: string;
+    slug: string;
+}
+export interface Heading {
+    id: string;
+    level: number;
+    text: string;
+}
+export interface Seo {
+    title: string;
+    description: string;
+    keywords: string[];
+    canonicalUrl: string;
+    noindex: boolean;
+    ogImage: Image | null;
+}
+export interface PostSummary {
+    id: string;
+    version: number;
+    slug: string;
+    url: string;
+    title: string;
+    excerpt: string;
+    readingTimeMinutes: number;
+    wordCount: number;
+    featuredImage: Image | null;
+    categories: Term[];
+    tags: Term[];
+    /** Always null in v1. */
+    author: {
+        name: string;
+        url: string | null;
+    } | null;
+    seo: Seo;
+    publishedAt: string;
+    updatedAt: string;
+}
+export interface Post extends PostSummary {
+    /** Sanitized by ContentAI. Does not include the title. */
+    html: string;
+    headings: Heading[];
+}
+export interface Pagination {
+    page: number;
+    perPage: number;
+    total: number;
+    totalPages: number;
+}
+export interface PostList {
+    data: PostSummary[];
+    pagination: Pagination;
+}
+export type PostLookup = {
+    type: "post";
+    post: Post;
+} | {
+    type: "redirect";
+    slug: string;
+    permanent: true;
+};
+export interface TermWithCount extends Term {
+    postCount: number;
+}
+export interface SitemapEntry {
+    slug: string;
+    url: string;
+    updatedAt: string;
+}
+export interface SiteInfo {
+    connectionId: string;
+    name: string;
+    siteUrl: string;
+    postUrlPattern: string;
+    delivery: "webhook" | "deploy_hook" | "none";
+}
+export interface ListPostsParams {
+    page?: number;
+    perPage?: number;
+    category?: string;
+    tag?: string;
+    sort?: "newest" | "oldest";
+}
+interface EventBase<T extends string, D> {
+    id: string;
+    type: T;
+    createdAt: string;
+    connectionId: string;
+    data: D;
+}
+export interface PostReference {
+    id: string;
+    slug: string;
+    version: number;
+}
+export type ContentAIEvent = EventBase<"post.published", {
+    post: Post;
+}> | EventBase<"post.updated", {
+    post: Post;
+    previousSlugs: string[];
+}> | EventBase<"post.unpublished", PostReference> | EventBase<"post.deleted", PostReference> | EventBase<"connection.ping", Record<string, never>>;
+export type ContentAIEventType = ContentAIEvent["type"];
+export type DeliveryErrorCode = "invalid_request" | "unauthorized" | "key_revoked" | "not_found" | "rate_limited" | "server_error";
+export {};

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * The ContentAI Delivery API contract, v1.
+ * Source of truth: docs/NEXTJS_CONTRACT.md in the ContentAI repository.
+ */
+export {};

package/dist/webhook.d.ts

@@ -0,0 +1,49 @@
+import type { ContentAIEvent } from "./types.js";
+/**
+ * Receiving ContentAI events, per the contract §5. Signatures follow the
+ * Standard Webhooks spec. Uses Web Crypto only, so it runs in Node.js and
+ * Edge route handlers alike.
+ */
+export declare class WebhookVerificationError extends Error {
+    constructor(message: string);
+}
+export interface VerifyOptions {
+    /** whsec_… secret, or several during rotation. */
+    secret: string | string[];
+    /** Maximum clock difference accepted, in seconds. Default 300. */
+    toleranceSeconds?: number;
+    /** For tests. */
+    now?: () => number;
+}
+export declare function sign(secret: string, id: string, timestamp: number, body: string): Promise<string>;
+/**
+ * Verifies a request's signature against its raw body, then parses it.
+ * Throws WebhookVerificationError on any mismatch.
+ */
+export declare function verifyWebhook(headers: Headers, rawBody: string, options: VerifyOptions): Promise<ContentAIEvent>;
+export interface WebhookHandlerOptions extends VerifyOptions {
+    /** Revalidate the event's cache tags (§7). Default true. */
+    revalidate?: boolean;
+    /**
+     * Called once per verified event, after revalidation. Copy posts into your
+     * own database here if you keep one; apply a post only when its version is
+     * higher than the one you hold, since retries can arrive out of order.
+     */
+    onEvent?: (event: ContentAIEvent) => void | Promise<void>;
+    /**
+     * Durable duplicate check across server instances. Return true if this
+     * event id was already processed. The handler also remembers recent ids in
+     * memory, which covers retries hitting the same instance.
+     */
+    isDuplicate?: (eventId: string) => boolean | Promise<boolean>;
+    /** For tests. Defaults to next/cache's revalidateTag. */
+    revalidateTag?: (tag: string, profile?: {
+        expire: number;
+    }) => void;
+}
+/**
+ * A ready-made POST route handler:
+ *
+ *   export const POST = createWebhookHandler({ secret: process.env.CONTENTAI_WEBHOOK_SECRET! });
+ */
+export declare function createWebhookHandler(options: WebhookHandlerOptions): (request: Request) => Promise<Response>;

package/dist/webhook.js

@@ -0,0 +1,117 @@
+import { tagsForEvent } from "./tags.js";
+/**
+ * Receiving ContentAI events, per the contract §5. Signatures follow the
+ * Standard Webhooks spec. Uses Web Crypto only, so it runs in Node.js and
+ * Edge route handlers alike.
+ */
+export class WebhookVerificationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "WebhookVerificationError";
+    }
+}
+const encoder = new TextEncoder();
+function base64ToBytes(value) {
+    const binary = atob(value);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+function bytesToBase64(bytes) {
+    let binary = "";
+    for (const byte of new Uint8Array(bytes))
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+function constantTimeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+export async function sign(secret, id, timestamp, body) {
+    if (!secret.startsWith("whsec_")) {
+        throw new WebhookVerificationError("The webhook secret must start with whsec_");
+    }
+    const key = await crypto.subtle.importKey("raw", base64ToBytes(secret.slice("whsec_".length)), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const mac = await crypto.subtle.sign("HMAC", key, encoder.encode(`${id}.${timestamp}.${body}`));
+    return `v1,${bytesToBase64(mac)}`;
+}
+/**
+ * Verifies a request's signature against its raw body, then parses it.
+ * Throws WebhookVerificationError on any mismatch.
+ */
+export async function verifyWebhook(headers, rawBody, options) {
+    const id = headers.get("webhook-id");
+    const timestampHeader = headers.get("webhook-timestamp");
+    const signatureHeader = headers.get("webhook-signature");
+    if (!id || !timestampHeader || !signatureHeader) {
+        throw new WebhookVerificationError("Missing webhook-id, webhook-timestamp or webhook-signature");
+    }
+    const timestamp = Number(timestampHeader);
+    const now = Math.floor((options.now ?? Date.now)() / 1000);
+    const tolerance = options.toleranceSeconds ?? 300;
+    if (!Number.isInteger(timestamp) || Math.abs(now - timestamp) > tolerance) {
+        throw new WebhookVerificationError("Timestamp outside the allowed window");
+    }
+    const secrets = Array.isArray(options.secret) ? options.secret : [options.secret];
+    const given = signatureHeader.split(" ").filter(Boolean);
+    for (const secret of secrets.filter(Boolean)) {
+        const expected = await sign(secret, id, timestamp, rawBody);
+        if (given.some((candidate) => constantTimeEqual(candidate, expected))) {
+            const event = JSON.parse(rawBody);
+            if (event.id !== id)
+                throw new WebhookVerificationError("Body id does not match webhook-id");
+            return event;
+        }
+    }
+    throw new WebhookVerificationError("No matching signature");
+}
+const RECENT_LIMIT = 1000;
+function json(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+/**
+ * A ready-made POST route handler:
+ *
+ *   export const POST = createWebhookHandler({ secret: process.env.CONTENTAI_WEBHOOK_SECRET! });
+ */
+export function createWebhookHandler(options) {
+    const recent = new Set();
+    return async function POST(request) {
+        // The signature covers the exact bytes, so read the raw body before parsing.
+        const rawBody = await request.text();
+        let event;
+        try {
+            event = await verifyWebhook(request.headers, rawBody, options);
+        }
+        catch (error) {
+            const message = error instanceof WebhookVerificationError ? error.message : "Invalid payload";
+            return json(401, { error: message });
+        }
+        if (recent.has(event.id) || (await options.isDuplicate?.(event.id))) {
+            return json(200, { received: true, duplicate: true });
+        }
+        if (options.revalidate !== false) {
+            const revalidateTag = options.revalidateTag ??
+                (await import("next/cache")).revalidateTag;
+            // { expire: 0 } expires immediately, which a webhook needs: Next.js 16
+            // otherwise serves stale content once (and warns about the one-argument
+            // form). Next.js 14 and 15 ignore the second argument.
+            for (const tag of tagsForEvent(event))
+                revalidateTag(tag, { expire: 0 });
+        }
+        // Unknown event types are acknowledged and ignored (contract §10).
+        await options.onEvent?.(event);
+        recent.add(event.id);
+        if (recent.size > RECENT_LIMIT)
+            recent.delete(recent.values().next().value);
+        return json(200, { received: true });
+    };
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@contentai/next",
+  "version": "0.1.0",
+  "description": "Connect any Next.js website to ContentAI: fetch published posts and handle signed webhook events.",
+  "license": "MIT",
+  "keywords": [
+    "contentai",
+    "nextjs",
+    "next",
+    "cms",
+    "headless-cms",
+    "webhook"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "bin": {
+    "contentai-next": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./webhook": {
+      "types": "./dist/webhook.d.ts",
+      "default": "./dist/webhook.js"
+    }
+  },
+  "engines": {
+    "node": ">=18.18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test \"src/__tests__/*.test.ts\"",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run typecheck && npm test"
+  },
+  "peerDependencies": {
+    "next": ">=14.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "next": "15.5.14",
+    "tsx": "^4.23.13",
+    "typescript": "^5"
+  }
+}