barakopress 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arnel Robles
+
+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,274 @@
+# barakoPress
+
+A blog engine for [barakoCMS](https://github.com/BaryoDev/barakoCMS), shipped as a package. Server
+rendered, cached until the CMS says otherwise, so ordinary traffic never reaches Postgres and a
+publish is live in one request.
+
+It is an engine, not a site. Content types in barakoCMS are defined at runtime, so a client's posts
+are as likely to be an `article` with a `Headline` as the blog blueprint's `post` with a `Title`.
+Every name is configuration, which is why the same package serves a site mounted at `/writing` with
+no authors and no categories.
+
+Part of BaryoDev, alongside [barakoCMS](https://github.com/BaryoDev/barakoCMS) (the API) and
+[barakoBrew](https://github.com/BaryoDev/barakoBrew) (the console).
+
+## Install
+
+```bash
+npm install barakopress
+```
+
+Needs Next 16 or later, React 19 or later, and Node 20.9 or later. Next and React are peer
+dependencies, so your app's copies are the ones that run.
+
+**No consumer build configuration.** The package ships compiled JavaScript and type declarations, so
+there is no `transpilePackages` line to add and nothing to configure in `next.config.ts`. If you are
+coming from 0.1.0, which shipped TypeScript sources, you can delete the
+`transpilePackages: ["barakopress"]` line when you upgrade. Leaving it in does no harm, it just does
+nothing.
+
+## Quick start
+
+One config file, then one route file per route you want. A route file is two or three lines: a Next
+route is decided by its path, and a package cannot create files in your app.
+
+**`press.config.ts`**
+
+```ts
+import { defineConfig } from "barakopress";
+
+export const config = defineConfig({
+  site: {
+    name: "My Blog",
+    tagline: "Things I wrote",
+    url: "https://myblog.example",
+  },
+});
+```
+
+That is everything a site on the `blog` blueprint needs. `CMS_URL` comes from the environment.
+
+**`app/page.tsx`**
+
+```tsx
+import { createBlogIndex } from "barakopress";
+import { config } from "@/press.config";
+
+export default createBlogIndex(config);
+export const revalidate = 300;
+```
+
+**`app/blog/[slug]/page.tsx`**
+
+```tsx
+import { createBlogPost, createPostMetadata } from "barakopress";
+import { config } from "@/press.config";
+
+export default createBlogPost(config);
+export const generateMetadata = createPostMetadata(config);
+export const revalidate = 300;
+```
+
+**`app/layout.tsx`**
+
+```tsx
+import "barakopress/styles.css";
+```
+
+`export const revalidate` stays in your file on purpose. Next reads route segment config from the
+file that owns the route and does not reliably follow a re-export, and the caching window is your
+decision, not the engine's.
+
+### The rest of the routes
+
+| Create | Export | From |
+| --- | --- | --- |
+| `app/page.tsx` | `default` | `createBlogIndex(config)` |
+| `app/blog/[slug]/page.tsx` | `default`, `generateMetadata` | `createBlogPost(config)`, `createPostMetadata(config)` |
+| `app/authors/[slug]/page.tsx` | `default` | `createArchive(config, "author")` |
+| `app/categories/[slug]/page.tsx` | `default` | `createArchive(config, "category")` |
+| `app/feed.xml/route.ts` | `GET` | `createFeed(config)` |
+| `app/sitemap.ts` | `default` | `createSitemap(config)` |
+| `app/robots.ts` | `default` | `createRobots(config)` |
+| `app/api/revalidate/route.ts` | `POST`, `GET` | `createRevalidateRoute(config)` |
+
+Mount only what you want. Nothing requires anything else. The paths only have to agree with the
+`routes` in your config, which is what every generated link is built from.
+
+`createBlogPostPreview` replaces `createBlogPost` when you want `?preview=TOKEN` to render a draft.
+It reads `searchParams`, which forces the route dynamic, so a site using `output: "export"` takes
+`createBlogPost` and gives up preview. `createPostStaticParams` and `createArchiveStaticParams` exist
+for that static case.
+
+`Card` and `PostView` are exported too, for a site that wants its own page but the engine's markup.
+
+## Configuring it
+
+`press.config.ts` is the one file a site owns, and the seam the whole package turns on.
+
+```ts
+export const config = defineConfig({
+  types:  { post: "article", author: undefined, category: undefined },
+  fields: { title: "Headline", slug: "Permalink", body: "Story", publishedAt: "RunDate" },
+  routes: { post: "/writing" },
+  site:   { name: "Client Three", url: "https://clientthree.example" },
+});
+```
+
+That is a test, not an illustration. CI installs the packed tarball into a separate app, points it at
+a content type called `article` with none of the blueprint's field names, no authors and no
+categories, and asserts the site renders, links to `/writing`, and produces a feed carrying the
+client's own identity.
+
+Only `title` and `body` are required in `fields`. Anything you leave out is a feature the site does
+without: the engine never asks the API for that data and never renders an empty slot for it. Naming a
+reference type you do not have is worse than useless, because `include=Author` is a 400 from the API
+for a post type with no such field.
+
+| Key | Default | What |
+| --- | --- | --- |
+| `site` | required | Name, tagline and absolute origin. Every absolute link is built from the origin |
+| `types` | `post`, `author`, `category` | The content type names |
+| `fields` | the blueprint's PascalCase names | Which field holds what |
+| `routes` | `/blog`, `/authors`, `/categories` | Where you mounted each route |
+| `pageSizes` | 20, 50, 1000, 50 | Index, feed, sitemap, archive |
+| `cacheTag` | `cms` | The tag this site purges. Two sites on one server need two tags |
+| `backstopSeconds` | 300 | How long a cached read may live with no webhook. 0 disables it |
+| `locale` | `en-GB` | Passed to `toLocaleDateString` |
+| `cmsUrl` | `CMS_URL`, or `http://localhost:5005` | Where the CMS is, from this server |
+| `tenant` | `CMS_TENANT` | Tenant slug, for a multi-tenant deployment |
+
+**Identity is build time.** The index, the feed, the sitemap and robots are prerendered, so anything
+`press.config.ts` reads from `process.env` is baked when you build, not when the server starts. Write
+per-site values as literals in that file. Only per-environment values (`CMS_URL`,
+`REVALIDATE_SECRET`) come from the environment, and neither of those is rendered. Getting this wrong
+is how a client site ships with the vendor's name in its masthead.
+
+## The caching design, which is the whole point
+
+A static site reads content at build time, so an edit is invisible until someone rebuilds and
+redeploys. A naive dynamic site reads the database on every page view. This does neither.
+
+```
+request  ->  Next cache  ->  HTML                        (no database)
+publish  ->  signed webhook  ->  revalidate  ->  next render reads once
+```
+
+Every read in `src/delivery.ts` is tagged with your `cacheTag`. `POST /api/revalidate` drops that tag
+the moment barakoCMS says something changed, so a publish is live in one request and the steady state
+is no database reads.
+
+Each read also carries a backstop, 300 seconds by default. That is not for correctness, it is for the
+deployment where nobody ever created the webhook: without it their blog would be empty forever and
+nothing would say why. With it, a missing webhook degrades publishing from instant to a few minutes.
+
+**The cache invalidation is configuration, not code.** In barakoBrew: a workflow on your post content
+type, trigger `Published`, one Webhook action with the URL and a shared secret. Nothing is deployed
+to change it.
+
+### Wiring the webhook
+
+1. Put a long random value in `REVALIDATE_SECRET` where your app runs.
+2. In barakoBrew, create a workflow on your post content type, event `Published`.
+3. Add a Webhook action with `Url` set to `https://your-site/api/revalidate` and `Secret` set to the
+   same value.
+
+**If your site sets `trailingSlash: true`, the webhook URL needs the slash.** Next redirects
+`/api/revalidate` to `/api/revalidate/` with a 308, and barakoCMS does not follow redirects on a
+webhook, deliberately: following one was an SSRF hole, because the guard checked only the first hop.
+So a URL without the slash gets a 308, the delivery is recorded as failed, it retries five times and
+gives up, and the cache is never purged. The site keeps working because of the backstop, so the only
+symptom is that publishing feels slow.
+
+barakoCMS refuses to sign a delivery to an `http://` URL unless `Webhooks:AllowInsecureSignedUrls` is
+on, which is for a loopback receiver in a lab. In production the URL is https, so this is not in your
+way.
+
+Verification follows the recipe in the API's `docs/webhooks.md`: HMAC-SHA256 over
+`"<timestamp>.<raw body>"`, compared in constant time, with a 300 second tolerance so a captured
+delivery cannot be replayed later, and each signature honoured once. An unsigned, missigned or stale
+delivery gets a 401. If `REVALIDATE_SECRET` is unset the endpoint answers 503 and purges nothing,
+because an open cache-purge endpoint is a free denial of service.
+
+## What it reads
+
+The `blog` blueprint barakoCMS ships: `post`, `category`, `author`, `page`. Apply it with
+`POST /api/content-types/blueprints/blog`. Field names are PascalCase because that is what the
+blueprint creates, and `src/cms.ts` is the only file in the package that knows any field name.
+
+Only published entries of a type opted into public delivery appear. Ordering is asked of the API
+rather than applied to the page that came back, because sorting one page of results gives you the
+newest of an arbitrary page.
+
+## Security
+
+Markdown is rendered as untrusted input in `src/markdown.ts`: raw HTML is escaped rather than passed
+through, link and image destinations must be http, https or mailto, and text is escaped into every
+attribute. An editor is authenticated, so this is the second line of defence, not the first. The
+trade is that an author cannot embed raw HTML or an iframe. When you want that, the answer is a
+content field your frontend renders deliberately, not a hole here.
+
+## Two behaviours that were measured, not assumed
+
+**`revalidateTag` needs `{ expire: 0 }`, not a named profile.** Next 16 made the second argument
+mandatory. Passing `"max"` left the prerendered sitemap stale indefinitely.
+
+**Cache warming after a purge does nothing, so there is none.** An earlier version fetched the main
+pages after purging, on the theory that Next serves one stale response after a purge and the server
+should absorb it rather than a reader. Measured against a CMS that logged every read, those fetches
+caused zero reads: `{ expire: 0 }` already makes the next request a blocking miss. It cost three
+requests per delivery and tripled what an attacker got from one captured signature, for nothing.
+
+## The reference deployment in this repository
+
+`app/` is not the product. It is a site that consumes this package by its name, exactly as yours
+does, so the package cannot quietly depend on something only its own repository has. It comes with a
+container, a compose stack with Caddy terminating TLS, and a BaryoVM release manifest.
+
+```bash
+cp .env.example .env      # point CMS_URL at your instance, set REVALIDATE_SECRET
+npm install
+npm run build && npm start
+```
+
+Deploying that stack to a VM:
+
+```bash
+baryovm vm provision blog1                     # or bring your own VM
+baryovm vm bootstrap blog1                     # installs Docker, and only Docker
+baryovm vm harden blog1                        # sshd policy and fail2ban
+baryovm stack add blog --vm blog1 --sudo --release-file ./baryovm.release.json
+baryovm stack release blog
+```
+
+Before the first release, three DNS names have to point at the machine (`SITE_DOMAIN`, `API_DOMAIN`,
+`CONSOLE_DOMAIN`) and a `.env` has to exist on it at `/opt/barakopress/.env`. The release refuses to
+start without that file, and refuses again if `REVALIDATE_SECRET` is empty, because a stack that
+comes up with no secret can never be told that content changed. Only ports 80 and 443 are published:
+the API, the console and the site are reachable only through Caddy on the compose network.
+
+## Working on the engine
+
+```bash
+npm install
+npm run build:package     # src to dist: JS, declarations and source maps
+npm run watch             # the same, in watch mode, while iterating
+npm run typecheck
+npm run build             # builds the package, then the reference app
+```
+
+`app/` imports `barakopress`, not `../src`, so it resolves through `dist` like any other consumer.
+That means `dist` has to exist before the app builds, which is why `npm run dev` and `npm run build`
+run the package build first. While changing `src/`, leave `npm run watch` going in one terminal and
+`next dev` in another.
+
+Why there is a build step at all, when every consumer is a Next app that could compile TypeScript
+itself: the decision and what it costs are recorded in [CLAUDE.md](CLAUDE.md).
+
+Releasing is in [RELEASING.md](RELEASING.md). No npm token is stored anywhere.
+
+## Status
+
+Early. The blog works end to end against a real instance. Known gaps, all tracked upstream: no media
+picker, no rich editor, no site settings object, and a content type's fields cannot be changed after
+it is created.

package/dist/cms.d.ts

@@ -0,0 +1,47 @@
+import type { PressConfig } from "./config.js";
+import { type PublicContent, type Seo } from "./delivery.js";
+export type { Seo };
+export interface Post {
+    id: string;
+    slug: string;
+    title: string;
+    excerpt?: string;
+    body: string;
+    publishedAt?: string;
+    coverImage?: string;
+    coverImageAlt?: string;
+    featured: boolean;
+    tags: string[];
+    author?: Ref;
+    category?: Ref;
+    seo?: Seo;
+}
+export interface Ref {
+    id: string;
+    slug: string;
+    name: string;
+}
+export declare function toPost(config: PressConfig, c: PublicContent): Post;
+export declare function listPosts(config: PressConfig, opts?: {
+    page?: number;
+    pageSize?: number;
+}): Promise<{
+    posts: Post[];
+    total: number;
+    hasNextPage: boolean;
+}>;
+export declare function getPost(config: PressConfig, slug: string): Promise<Post | null>;
+export declare function getPostPreview(config: PressConfig, slug: string, token: string): Promise<Post | null>;
+/** Posts by author or category. Null when the site has no such type, or the slug is unknown. */
+export declare function listPostsBy(config: PressConfig, which: "author" | "category", slug: string): Promise<Post[] | null>;
+export interface Term {
+    id: string;
+    slug: string;
+    name: string;
+    description?: string;
+    photo?: string;
+    website?: string;
+}
+export declare function getTerm(config: PressConfig, which: "author" | "category", slug: string): Promise<Term | null>;
+export declare function formatDate(config: PressConfig, value?: string): string;
+//# sourceMappingURL=cms.d.ts.map

package/dist/cms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cms.d.ts","sourceRoot":"","sources":["../src/cms.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAA+B,KAAK,aAAa,EAAE,KAAK,GAAG,EAAE,MAAM,eAAe,CAAC;AAE1F,YAAY,EAAE,GAAG,EAAE,CAAC;AAWpB,MAAM,WAAW,IAAI;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,MAAM,CAAC,EAAE,GAAG,CAAC;IACb,QAAQ,CAAC,EAAE,GAAG,CAAC;IACf,GAAG,CAAC,EAAE,GAAG,CAAC;CACb;AAED,MAAM,WAAW,GAAG;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CAChB;AAuBD,wBAAgB,MAAM,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,EAAE,aAAa,GAAG,IAAI,CAmBlE;AAYD,wBAAsB,SAAS,CAC3B,MAAM,EAAE,WAAW,EACnB,IAAI,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAChD,OAAO,CAAC;IAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,OAAO,CAAA;CAAE,CAAC,CAYjE;AAED,wBAAsB,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAGrF;AAED,wBAAsB,cAAc,CAChC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAGtB;AAWD,gGAAgG;AAChG,wBAAsB,WAAW,CAC7B,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,QAAQ,GAAG,UAAU,EAC5B,IAAI,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,CAexB;AAED,MAAM,WAAW,IAAI;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAUD,wBAAsB,OAAO,CACzB,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,QAAQ,GAAG,UAAU,EAC5B,IAAI,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAetB;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAMtE"}

package/dist/cms.js

@@ -0,0 +1,131 @@
+import { includesFor } from "./config.js";
+import { bySlug, bySlugPreview, list } from "./delivery.js";
+const str = (v) => (typeof v === "string" ? v : "");
+/** Reads a field by its configured name, or undefined when the site has no such field. */
+function field(data, name) {
+    return name ? data[name] : undefined;
+}
+/*
+ * A resolved reference. `include` gives back the whole target entry, so this handles that and a
+ * bare id, and gives up rather than inventing a label when neither a name nor a slug is there.
+ */
+function toRef(config, v) {
+    if (!v || typeof v !== "object")
+        return undefined;
+    const d = v;
+    const data = (d.data ?? d);
+    const name = str(data.Name) || str(data.Title) || str(field(data, config.fields.title));
+    const slug = str(d.slug) || str(field(data, config.fields.slug)) || str(data.Slug);
+    if (!name && !slug)
+        return undefined;
+    return { id: str(d.id), slug, name: name || slug };
+}
+export function toPost(config, c) {
+    const d = c.data;
+    const f = config.fields;
+    const tags = field(d, f.tags);
+    return {
+        id: c.id,
+        slug: c.slug ?? str(field(d, f.slug)),
+        title: str(field(d, f.title)) || "Untitled",
+        excerpt: str(field(d, f.excerpt)) || undefined,
+        body: str(field(d, f.body)),
+        publishedAt: str(field(d, f.publishedAt)) || c.createdAt || undefined,
+        coverImage: str(field(d, f.coverImage)) || undefined,
+        coverImageAlt: str(field(d, f.coverImageAlt)) || undefined,
+        featured: field(d, f.featured) === true,
+        tags: Array.isArray(tags) ? tags.filter((t) => typeof t === "string") : [],
+        author: toRef(config, field(d, f.author)),
+        category: toRef(config, field(d, f.category)),
+        seo: c.seo ?? undefined,
+    };
+}
+/*
+ * Ordering is asked of the API, not done here.
+ *
+ * Sorting the page that came back only orders those rows, so on a blog past one page the "newest"
+ * list is newest-of-an-arbitrary-page. The API can order every row, so it does.
+ */
+function sortKey(config) {
+    return config.fields.publishedAt ? `-${config.fields.publishedAt}` : undefined;
+}
+export async function listPosts(config, opts = {}) {
+    const res = await list(config, config.types.post, {
+        page: opts.page ?? 1,
+        pageSize: opts.pageSize ?? config.pageSizes.index,
+        include: includesFor(config),
+        sort: sortKey(config),
+    });
+    return {
+        posts: res.items.map((c) => toPost(config, c)),
+        total: res.totalItems,
+        hasNextPage: res.hasNextPage,
+    };
+}
+export async function getPost(config, slug) {
+    const c = await bySlug(config, config.types.post, slug);
+    return c ? toPost(config, c) : null;
+}
+export async function getPostPreview(config, slug, token) {
+    const c = await bySlugPreview(config, config.types.post, slug, token);
+    return c ? toPost(config, c) : null;
+}
+/*
+ * Filtering by a reference takes the target's id, not its slug, so an archive is two calls:
+ * resolve the slug, then filter. Both are cached and tagged, so it costs two reads once.
+ */
+async function idForSlug(config, type, slug) {
+    const c = await bySlug(config, type, slug);
+    return c?.id ?? null;
+}
+/** Posts by author or category. Null when the site has no such type, or the slug is unknown. */
+export async function listPostsBy(config, which, slug) {
+    const type = config.types[which];
+    const fieldName = config.fields[which];
+    if (!type || !fieldName)
+        return null;
+    const id = await idForSlug(config, type, slug);
+    if (!id)
+        return null;
+    const res = await list(config, config.types.post, {
+        pageSize: config.pageSizes.archive,
+        include: includesFor(config),
+        filter: [[fieldName, "eq", id]],
+        sort: sortKey(config),
+    });
+    return res.items.map((c) => toPost(config, c));
+}
+/*
+ * An author or category entry, for the heading of its archive page.
+ *
+ * These secondary types keep the blueprint's names with the post type's title and slug as
+ * fallbacks. One flat field map cannot describe three types, and a model whose author type
+ * differs wholesale wants its own screen. That is a fair boundary for the engine, and it is
+ * stated here so nobody discovers it by reading the source.
+ */
+export async function getTerm(config, which, slug) {
+    const type = config.types[which];
+    if (!type)
+        return null;
+    const c = await bySlug(config, type, slug);
+    if (!c)
+        return null;
+    const d = c.data;
+    return {
+        id: c.id,
+        slug: c.slug ?? (str(field(d, config.fields.slug)) || str(d.Slug)),
+        name: str(d.Name) || str(d.Title) || str(field(d, config.fields.title)) || "Untitled",
+        description: str(d.Description) || str(d.Bio) || undefined,
+        photo: str(d.Photo) || undefined,
+        website: str(d.Website) || undefined,
+    };
+}
+export function formatDate(config, value) {
+    if (!value)
+        return "";
+    const d = new Date(value);
+    return Number.isNaN(d.getTime())
+        ? ""
+        : d.toLocaleDateString(config.locale, { day: "numeric", month: "long", year: "numeric" });
+}
+//# sourceMappingURL=cms.js.map

package/dist/cms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cms.js","sourceRoot":"","sources":["../src/cms.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -0,0 +1,91 @@
+export interface TypeNames {
+    /** The content type holding posts. */
+    post: string;
+    /** The type an author reference points at. Omit if the model has no authors. */
+    author?: string;
+    /** The type a category reference points at. Omit if the model has no categories. */
+    category?: string;
+}
+/**
+ * Which field on the post type holds what.
+ *
+ * Only `title` and `body` are required; everything else is a feature the site does without if the
+ * model has no field for it. An absent name means the engine never asks for that data and never
+ * renders it, rather than rendering an empty slot.
+ */
+export interface FieldMap {
+    title: string;
+    body: string;
+    slug?: string;
+    excerpt?: string;
+    publishedAt?: string;
+    coverImage?: string;
+    coverImageAlt?: string;
+    featured?: string;
+    tags?: string;
+    /** The reference field pointing at the author type. */
+    author?: string;
+    /** The reference field pointing at the category type. */
+    category?: string;
+}
+/** Where the consumer mounted each route, so generated links match the app's real shape. */
+export interface RouteMap {
+    /** The post route's prefix, for example "/blog" or "/writing". */
+    post: string;
+    author?: string;
+    category?: string;
+}
+export interface PageSizes {
+    index: number;
+    feed: number;
+    sitemap: number;
+    archive: number;
+}
+export interface SiteIdentity {
+    name: string;
+    tagline?: string;
+    /** Absolute origin, used for every absolute link in the feed, sitemap and robots. */
+    url: string;
+}
+export interface PressConfig {
+    types: TypeNames;
+    fields: FieldMap;
+    routes: RouteMap;
+    site: SiteIdentity;
+    pageSizes: PageSizes;
+    /** The cache tag this site purges. Two sites on one server need two tags. */
+    cacheTag: string;
+    /** How long a cached read may live with no webhook. Zero disables the backstop. */
+    backstopSeconds: number;
+    /** Passed to toLocaleDateString. */
+    locale: string;
+    /** Where the CMS is, from this server. */
+    cmsUrl: string;
+    /** Tenant slug, for a multi-tenant deployment. */
+    tenant?: string;
+}
+export type PressConfigInput = {
+    types?: Partial<TypeNames>;
+    fields?: Partial<FieldMap>;
+    routes?: Partial<RouteMap>;
+    site?: Partial<SiteIdentity>;
+    pageSizes?: Partial<PageSizes>;
+} & Partial<Omit<PressConfig, "types" | "fields" | "routes" | "site" | "pageSizes">>;
+/**
+ * Builds a complete config from a partial one.
+ *
+ * Site name and URL have no sensible default: a fallback of the engine's own name is how a client
+ * site ends up with the vendor's brand in its masthead, so they are required and the type says so.
+ */
+export declare function defineConfig(input: PressConfigInput & {
+    site: SiteIdentity;
+}): PressConfig;
+/**
+ * The reference fields worth resolving in one request, as the API's `include` expects them.
+ *
+ * Only names the site actually has. Sending `include=Author,Category` unconditionally is a 400
+ * from the API for any post type without both fields, which is every model that is not the blog
+ * blueprint.
+ */
+export declare function includesFor(config: PressConfig): string[];
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,SAAS;IACtB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,4FAA4F;AAC5F,MAAM,WAAW,QAAQ;IACrB,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,SAAS;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,GAAG,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IACxB,KAAK,EAAE,SAAS,CAAC;IACjB,MAAM,EAAE,QAAQ,CAAC;IACjB,MAAM,EAAE,QAAQ,CAAC;IACjB,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,EAAE,SAAS,CAAC;IACrB,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,mFAAmF;IACnF,eAAe,EAAE,MAAM,CAAC;IACxB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,gBAAgB,GAAG;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3B,IAAI,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAC;IAC7B,SAAS,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;CAClC,GAAG,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC;AAwBrF;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,gBAAgB,GAAG;IAAE,IAAI,EAAE,YAAY,CAAA;CAAE,GAAG,WAAW,CAmB1F;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,EAAE,CAMzD"}

package/dist/config.js

@@ -0,0 +1,75 @@
+/*
+ * The seam.
+ *
+ * Everything a site differs on lives here, so a consumer configures the engine instead of forking
+ * it. That matters because barakoCMS content types are defined at runtime: a client's posts are as
+ * likely to be `article` with a `Headline` as they are to be the blog blueprint's `post` and
+ * `Title`. An engine that compiles one shape in is one client's blog wearing a package name.
+ *
+ * The defaults are the `blog` blueprint the API ships, so a site that used the blueprint passes
+ * nothing and gets the same behaviour as before this existed.
+ *
+ * Config reaches the screens through factories rather than a global, because a Next route is a
+ * file and a package cannot write files into someone else's app. A consumer's route file calls
+ * `createBlogIndex(config)` and exports the result. One import, one call, full control.
+ */
+/** The `blog` blueprint, which is what `POST /api/content-types/blueprints/blog` creates. */
+const BLOG_BLUEPRINT = {
+    types: { post: "post", author: "author", category: "category" },
+    fields: {
+        title: "Title",
+        slug: "Slug",
+        excerpt: "Excerpt",
+        body: "Body",
+        coverImage: "CoverImage",
+        coverImageAlt: "CoverImageAlt",
+        publishedAt: "PublishedAt",
+        featured: "Featured",
+        tags: "Tags",
+        author: "Author",
+        category: "Category",
+    },
+};
+function trimSlash(path) {
+    return path.replace(/\/+$/, "");
+}
+/**
+ * Builds a complete config from a partial one.
+ *
+ * Site name and URL have no sensible default: a fallback of the engine's own name is how a client
+ * site ends up with the vendor's brand in its masthead, so they are required and the type says so.
+ */
+export function defineConfig(input) {
+    const routes = { post: "/blog", author: "/authors", category: "/categories", ...input.routes };
+    return {
+        types: { ...BLOG_BLUEPRINT.types, ...input.types },
+        fields: { ...BLOG_BLUEPRINT.fields, ...input.fields },
+        routes: {
+            post: trimSlash(routes.post),
+            author: routes.author ? trimSlash(routes.author) : undefined,
+            category: routes.category ? trimSlash(routes.category) : undefined,
+        },
+        site: { ...input.site, url: trimSlash(input.site.url) },
+        pageSizes: { index: 20, feed: 50, sitemap: 1000, archive: 50, ...input.pageSizes },
+        cacheTag: input.cacheTag ?? "cms",
+        backstopSeconds: input.backstopSeconds ?? 300,
+        locale: input.locale ?? "en-GB",
+        cmsUrl: trimSlash(input.cmsUrl ?? process.env.CMS_URL ?? "http://localhost:5005"),
+        tenant: input.tenant ?? process.env.CMS_TENANT ?? undefined,
+    };
+}
+/**
+ * The reference fields worth resolving in one request, as the API's `include` expects them.
+ *
+ * Only names the site actually has. Sending `include=Author,Category` unconditionally is a 400
+ * from the API for any post type without both fields, which is every model that is not the blog
+ * blueprint.
+ */
+export function includesFor(config) {
+    const wanted = [
+        config.types.author ? config.fields.author : undefined,
+        config.types.category ? config.fields.category : undefined,
+    ];
+    return wanted.filter((f) => Boolean(f));
+}
+//# sourceMappingURL=config.js.map