@carlonicora/nextjs-jsonapi 5.3.0 → 5.4.0

package/src/features/blog/data/BlogPostTranslationService.ts

@@ -0,0 +1,30 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules } from "../../../core";
+import { BLOG_ACTION } from "../types/blog.constants";
+import { BlogPostTranslationInput, BlogPostTranslationInterface } from "./BlogPostTranslationInterface";
+
+export class BlogPostTranslationService extends AbstractService {
+  static async update(params: BlogPostTranslationInput): Promise<BlogPostTranslationInterface> {
+    return this.callApi<BlogPostTranslationInterface>({
+      type: Modules.BlogPostTranslation,
+      method: HttpMethod.PUT,
+      endpoint: new EndpointCreator({ endpoint: Modules.BlogPostTranslation, id: params.id }).generate(),
+      input: params,
+    });
+  }
+
+  /**
+   * POST blog-post-translations/:id/retranslate. Re-queues this one language
+   * from the current original. Replies 204.
+   */
+  static async retranslate(params: { id: string }): Promise<void> {
+    await this.callApi({
+      type: Modules.BlogPostTranslation,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({
+        endpoint: Modules.BlogPostTranslation,
+        id: params.id,
+        childEndpoint: BLOG_ACTION.retranslate,
+      }).generate(),
+    });
+  }
+}

package/src/features/blog/data/BlogSettings.ts

@@ -0,0 +1,37 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { BLOG_LIST_LAYOUTS, BlogListLayout } from "../types/blog.constants";
+import { BlogSettingsInput, BlogSettingsInterface } from "./BlogSettingsInterface";
+
+export class BlogSettings extends AbstractApiData implements BlogSettingsInterface {
+  private _listLayout?: BlogListLayout;
+
+  get listLayout(): BlogListLayout {
+    return this._listLayout ?? "featured";
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const listLayout = data.jsonApi.attributes?.listLayout;
+    this._listLayout = BLOG_LIST_LAYOUTS.includes(listLayout) ? listLayout : undefined;
+
+    return this;
+  }
+
+  createJsonApi(data: BlogSettingsInput) {
+    const response: any = {
+      data: {
+        type: Modules.BlogSettings.name,
+        id: data.id,
+        attributes: {},
+        meta: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    response.data.attributes.listLayout = data.listLayout;
+
+    return response;
+  }
+}

package/src/features/blog/data/BlogSettingsInterface.ts

@@ -0,0 +1,11 @@
+import { ApiDataInterface } from "../../../core";
+import { BlogListLayout } from "../types/blog.constants";
+
+export type BlogSettingsInput = {
+  id: string;
+  listLayout: BlogListLayout;
+};
+
+export interface BlogSettingsInterface extends ApiDataInterface {
+  get listLayout(): BlogListLayout;
+}

package/src/features/blog/data/BlogSettingsService.ts

@@ -0,0 +1,24 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules } from "../../../core";
+import { BlogSettingsInput, BlogSettingsInterface } from "./BlogSettingsInterface";
+
+export class BlogSettingsService extends AbstractService {
+  /**
+   * GET blog-settings: the stored singleton, or the API's default.
+   */
+  static async get(): Promise<BlogSettingsInterface> {
+    return this.callApi<BlogSettingsInterface>({
+      type: Modules.BlogSettings,
+      method: HttpMethod.GET,
+      endpoint: new EndpointCreator({ endpoint: Modules.BlogSettings }).generate(),
+    });
+  }
+
+  static async save(params: BlogSettingsInput): Promise<BlogSettingsInterface> {
+    return this.callApi<BlogSettingsInterface>({
+      type: Modules.BlogSettings,
+      method: HttpMethod.PUT,
+      endpoint: new EndpointCreator({ endpoint: Modules.BlogSettings, id: params.id }).generate(),
+      input: params,
+    });
+  }
+}

package/src/features/blog/data/index.ts

@@ -0,0 +1,17 @@
+export * from "./BlogPostInterface";
+export * from "./BlogPost";
+export * from "./BlogPostService";
+export * from "./BlogPostTranslationInterface";
+export * from "./BlogPostTranslation";
+export * from "./BlogPostTranslationService";
+export * from "./BlogCategoryInterface";
+export * from "./BlogCategory";
+export * from "./BlogCategoryService";
+export * from "./BlogCategoryTranslationInterface";
+export * from "./BlogCategoryTranslation";
+export * from "./BlogCategoryTranslationService";
+export * from "./BlogSettingsInterface";
+export * from "./BlogSettings";
+export * from "./BlogSettingsService";
+export * from "./BlogPostFields";
+export * from "./BlogCategoryFields";

package/src/features/blog/hooks/index.ts

@@ -0,0 +1,3 @@
+export * from "./useBlogPostTableStructure";
+export * from "./useBlogCategoryTableStructure";
+export * from "./useBlogCategoryNames";

package/src/features/blog/hooks/useBlogCategoryNames.ts

@@ -0,0 +1,34 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import { BlogCategoryService } from "../data";
+import { blogCategoryAdminName } from "../components/admin/BlogTranslationStatus";
+
+/**
+ * Category names for the admin views, in each category's original language.
+ *
+ * A post response includes its categories without their translations (the
+ * framework includes one level), so the name is not on the included record.
+ * The category list does include the translations: it is read once and the
+ * returned lookup maps a category id to its name ("" while loading).
+ */
+export function useBlogCategoryNames(): (categoryId: string) => string {
+  const [names, setNames] = useState<Record<string, string>>({});
+
+  useEffect(() => {
+    let cancelled = false;
+    BlogCategoryService.findMany({ fetchAll: true })
+      .then((categories) => {
+        if (cancelled) return;
+        setNames(Object.fromEntries(categories.map((category) => [category.id, blogCategoryAdminName(category)])));
+      })
+      .catch(() => {
+        // The names are decoration on an admin page: a failed read leaves the ids unnamed.
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  return useCallback((categoryId: string) => names[categoryId] ?? "", [names]);
+}

package/src/features/blog/hooks/useBlogCategoryTableStructure.tsx

@@ -0,0 +1,84 @@
+"use client";
+
+import { ColumnDef } from "@tanstack/react-table";
+import { useTranslations } from "next-intl";
+import { useMemo } from "react";
+import { registerTableGenerator, TableContent, UseTableStructureHook } from "../../../hooks";
+import { BlogCategoryEditor } from "../components/admin/BlogCategoryEditor";
+import { blogCategoryAdminName } from "../components/admin/BlogTranslationStatus";
+import { BlogCategoryFields, BlogCategoryInterface } from "../data";
+
+/**
+ * Admin categories table: the name (original language) opens BlogCategoryEditor
+ * for that row; "languages ready" counts completed translations. Categories have
+ * no page of their own. Mirrors hooks/useEmailAutomationTableStructure.tsx in
+ * features/email-automation.
+ */
+export const useBlogCategoryTableStructure: UseTableStructureHook<BlogCategoryInterface, BlogCategoryFields> = (
+  params,
+) => {
+  const t = useTranslations();
+  const refresh = params.dataRetriever?.refresh;
+
+  const tableData = useMemo(() => {
+    return params.data.map((category: BlogCategoryInterface) => {
+      const entry: TableContent<BlogCategoryInterface> = { jsonApiData: category };
+      params.fields.forEach((field) => {
+        entry[field] = (category as any)[field as keyof BlogCategoryInterface];
+      });
+      return entry;
+    });
+  }, [params.data, params.fields]);
+
+  const fieldColumnMap: Partial<Record<BlogCategoryFields, () => any>> = {
+    [BlogCategoryFields.name]: () => ({
+      id: BlogCategoryFields.name,
+      accessorKey: BlogCategoryFields.name,
+      header: t("blog.fields.name"),
+      cell: ({ row }: { row: TableContent<BlogCategoryInterface> }) => {
+        const category: BlogCategoryInterface = row.original.jsonApiData;
+        return (
+          <BlogCategoryEditor
+            category={category}
+            onSuccess={refresh}
+            trigger={
+              <button type="button" className="text-primary text-start font-medium">
+                {blogCategoryAdminName(category) || category.id}
+              </button>
+            }
+          />
+        );
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [BlogCategoryFields.languages]: () => ({
+      id: BlogCategoryFields.languages,
+      accessorKey: BlogCategoryFields.languages,
+      header: t("blog.fields.languages"),
+      cell: ({ row }: { row: TableContent<BlogCategoryInterface> }) => {
+        const category: BlogCategoryInterface = row.original.jsonApiData;
+        const total = category.translations.length;
+        if (total === 0) return <span className="text-muted-foreground text-xs">—</span>;
+        const ready = category.translations.filter((translation) => translation.aiStatus === "completed").length;
+        return (
+          <span className="block text-xs tabular-nums text-end">
+            {ready}/{total}
+          </span>
+        );
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+  };
+
+  const columns = useMemo(() => {
+    return params.fields.map((field) => fieldColumnMap[field]?.()).filter((col) => col !== undefined) as ColumnDef<
+      TableContent<BlogCategoryInterface>
+    >[];
+  }, [params.fields, fieldColumnMap, t, refresh]);
+
+  return useMemo(() => ({ data: tableData, columns: columns }), [tableData, columns]);
+};
+
+registerTableGenerator("blog-categories", useBlogCategoryTableStructure);

package/src/features/blog/hooks/useBlogPostTableStructure.tsx

@@ -0,0 +1,126 @@
+"use client";
+
+import { ColumnDef } from "@tanstack/react-table";
+import { useTranslations } from "next-intl";
+import { useMemo } from "react";
+import { Modules } from "../../../core";
+import { registerTableGenerator, TableContent, usePageUrlGenerator, UseTableStructureHook } from "../../../hooks";
+import { useI18nLocale } from "../../../i18n";
+import { Badge, Link } from "../../../shadcnui";
+import { BLOG_STATUS_BADGE } from "../components/admin/BlogTranslationStatus";
+import { useBlogCategoryNames } from "./useBlogCategoryNames";
+import { BlogPostFields, BlogPostInterface } from "../data";
+
+/**
+ * Admin posts table: title (original language, links to the post page),
+ * status, categories, published date and "languages ready" (completed
+ * translations / all translations). Mirrors hooks/useEmailAutomationTableStructure.tsx
+ * in features/email-automation.
+ */
+export const useBlogPostTableStructure: UseTableStructureHook<BlogPostInterface, BlogPostFields> = (params) => {
+  const t = useTranslations();
+  const locale = useI18nLocale();
+  const generateUrl = usePageUrlGenerator();
+  const categoryName = useBlogCategoryNames();
+
+  const tableData = useMemo(() => {
+    return params.data.map((post: BlogPostInterface) => {
+      const entry: TableContent<BlogPostInterface> = { jsonApiData: post };
+      params.fields.forEach((field) => {
+        entry[field] = (post as any)[field as keyof BlogPostInterface];
+      });
+      return entry;
+    });
+  }, [params.data, params.fields]);
+
+  const fieldColumnMap: Partial<Record<BlogPostFields, () => any>> = {
+    [BlogPostFields.title]: () => ({
+      id: BlogPostFields.title,
+      accessorKey: BlogPostFields.title,
+      header: t("blog.fields.title"),
+      cell: ({ row }: { row: TableContent<BlogPostInterface> }) => {
+        const post: BlogPostInterface = row.original.jsonApiData;
+        return (
+          <Link href={generateUrl({ page: Modules.BlogPost, id: post.id })}>
+            {post.original?.title ?? post.title ?? post.id}
+          </Link>
+        );
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [BlogPostFields.status]: () => ({
+      id: BlogPostFields.status,
+      accessorKey: BlogPostFields.status,
+      header: t("blog.fields.status"),
+      cell: ({ row }: { row: TableContent<BlogPostInterface> }) => {
+        const post: BlogPostInterface = row.original.jsonApiData;
+        const label = {
+          draft: t("blog.status.draft"),
+          published: t("blog.status.published"),
+          unpublished: t("blog.status.unpublished"),
+        }[post.status];
+        return <Badge variant={BLOG_STATUS_BADGE[post.status] ?? "softGray"}>{label ?? post.status}</Badge>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [BlogPostFields.categories]: () => ({
+      id: BlogPostFields.categories,
+      accessorKey: BlogPostFields.categories,
+      header: t("blog.fields.categories"),
+      cell: ({ row }: { row: TableContent<BlogPostInterface> }) => {
+        const post: BlogPostInterface = row.original.jsonApiData;
+        const names = post.categories.map((category) => categoryName(category.id)).filter(Boolean);
+        if (names.length === 0) return <span className="text-muted-foreground text-xs">—</span>;
+        return <span className="text-xs">{names.join(", ")}</span>;
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [BlogPostFields.publishedAt]: () => ({
+      id: BlogPostFields.publishedAt,
+      accessorKey: BlogPostFields.publishedAt,
+      header: t("blog.fields.publishedAt"),
+      cell: ({ row }: { row: TableContent<BlogPostInterface> }) => {
+        const post: BlogPostInterface = row.original.jsonApiData;
+        if (!post.publishedAt) return <span className="text-muted-foreground text-xs">—</span>;
+        return (
+          <span className="text-xs tabular-nums">
+            {post.publishedAt.toLocaleDateString(locale, { dateStyle: "medium" })}
+          </span>
+        );
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+    [BlogPostFields.languages]: () => ({
+      id: BlogPostFields.languages,
+      accessorKey: BlogPostFields.languages,
+      header: t("blog.fields.languages"),
+      cell: ({ row }: { row: TableContent<BlogPostInterface> }) => {
+        const post: BlogPostInterface = row.original.jsonApiData;
+        const total = post.translations.length;
+        if (total === 0) return <span className="text-muted-foreground text-xs">—</span>;
+        const ready = post.translations.filter((translation) => translation.aiStatus === "completed").length;
+        return (
+          <span className="block text-xs tabular-nums text-end">
+            {ready}/{total}
+          </span>
+        );
+      },
+      enableSorting: false,
+      enableHiding: false,
+    }),
+  };
+
+  const columns = useMemo(() => {
+    return params.fields.map((field) => fieldColumnMap[field]?.()).filter((col) => col !== undefined) as ColumnDef<
+      TableContent<BlogPostInterface>
+    >[];
+  }, [params.fields, fieldColumnMap, t, generateUrl, locale, categoryName]);
+
+  return useMemo(() => ({ data: tableData, columns: columns }), [tableData, columns]);
+};
+
+registerTableGenerator("blog-posts", useBlogPostTableStructure);

package/src/features/blog/index.ts

@@ -0,0 +1,15 @@
+// Client-only public barrel for the blog feature.
+// Consumed via `@carlonicora/nextjs-jsonapi/blog`. Tsup adds a top-level
+// "use client" directive to the bundled output via clientEntries.
+//
+// Models, services and modules are server-safe and ship from
+// `@carlonicora/nextjs-jsonapi/core`. Server fetchers ship from
+// `@carlonicora/nextjs-jsonapi/blog/server`.
+
+export * from "./components/admin";
+export * from "./components/public";
+export * from "./contexts";
+// Imported for its registerTableGenerator side effect as well as its exports.
+export * from "./hooks";
+export * from "./types/blog.constants";
+export type { PublicBlogCategory, PublicBlogList, PublicBlogPost } from "./types/blog-public.types";

package/src/features/blog/server/fetchers.ts

@@ -0,0 +1,120 @@
+import { EndpointCreator, Modules } from "../../../core";
+import { ServerJsonApiGet } from "../../../server/JsonApiServer";
+import { BlogCategoryInterface } from "../data/BlogCategoryInterface";
+import { BlogPostInterface } from "../data/BlogPostInterface";
+import { BlogSettingsInterface } from "../data/BlogSettingsInterface";
+import { BLOG_ACTION, BLOG_LIST_LAYOUTS, BLOG_PUBLIC_PREFIX, BlogListLayout } from "../types/blog.constants";
+import { PublicBlogCategory, PublicBlogList, PublicBlogPost } from "../types/blog-public.types";
+import { toPublicBlogCategory, toPublicBlogPost } from "./toPublic";
+
+// Public, token-free reads for the marketing blog pages.
+//
+// `cache: "minutes"` is a cacheLife profile name: the GET goes through
+// cachedServerGet ("use cache"), so an admin change shows up within about a
+// minute. Nothing connects API or worker writes to the web cache, and
+// translations finish asynchronously in the worker, so there is no tag to expire.
+//
+// Each classKey is built INSIDE the function, never at module scope: reading
+// Modules.X while the module evaluates throws "Module X not registered" in build
+// workers that never ran the app's bootstrapper (see the app's publicHowTo.ts).
+
+const BLOG_PAGE_SIZE = 12;
+
+const publicPostsEndpoint = () => `${BLOG_PUBLIC_PREFIX}/${Modules.BlogPost.name}`;
+
+const asArray = <T>(data: unknown): T[] => (Array.isArray(data) ? data : data ? [data] : []) as T[];
+
+export async function fetchPublicBlogPosts(params: {
+  language: string;
+  categorySlug?: string;
+  search?: string;
+  page: number;
+}): Promise<PublicBlogList> {
+  // Matches the API cap (120 = 10 pages of 12); a larger ?page= is served as the last allowed one.
+  const page = Math.min(10, Math.max(1, Math.floor(params.page || 1)));
+  const size = BLOG_PAGE_SIZE * page;
+
+  const endpoint = new EndpointCreator({ endpoint: publicPostsEndpoint() });
+  endpoint.addAdditionalParam("language", params.language);
+  if (params.categorySlug) endpoint.addAdditionalParam("category", encodeURIComponent(params.categorySlug));
+  if (params.search) endpoint.addAdditionalParam("search", encodeURIComponent(params.search));
+  endpoint.addAdditionalParam("page[size]", String(size));
+
+  const res = await ServerJsonApiGet({
+    classKey: { ...Modules.BlogPost, cache: "minutes" },
+    endpoint: endpoint.generate(),
+    language: params.language,
+  });
+  if (!res.ok) return { posts: [], hasMore: false };
+
+  const posts = asArray<BlogPostInterface>(res.data).map(toPublicBlogPost);
+  const total = Number(res.meta?.total);
+  const hasMore = Number.isFinite(total) ? total > posts.length : false;
+
+  return { posts, hasMore };
+}
+
+export async function fetchPublicBlogPost(params: { language: string; slug: string }): Promise<PublicBlogPost | null> {
+  const endpoint = new EndpointCreator({ endpoint: publicPostsEndpoint(), id: encodeURIComponent(params.slug) });
+  endpoint.addAdditionalParam("language", params.language);
+
+  const res = await ServerJsonApiGet({
+    classKey: { ...Modules.BlogPost, cache: "minutes" },
+    endpoint: endpoint.generate(),
+    language: params.language,
+  });
+  if (!res.ok) return null;
+
+  const post = asArray<BlogPostInterface>(res.data)[0];
+  return post ? toPublicBlogPost(post) : null;
+}
+
+export async function fetchRelatedBlogPosts(params: { language: string; slug: string }): Promise<PublicBlogPost[]> {
+  const endpoint = new EndpointCreator({
+    endpoint: publicPostsEndpoint(),
+    id: encodeURIComponent(params.slug),
+    childEndpoint: BLOG_ACTION.related,
+  });
+  endpoint.addAdditionalParam("language", params.language);
+
+  const res = await ServerJsonApiGet({
+    classKey: { ...Modules.BlogPost, cache: "minutes" },
+    endpoint: endpoint.generate(),
+    language: params.language,
+  });
+  if (!res.ok) return [];
+
+  return asArray<BlogPostInterface>(res.data).map(toPublicBlogPost);
+}
+
+export async function fetchPublicBlogCategories(params: { language: string }): Promise<PublicBlogCategory[]> {
+  const endpoint = new EndpointCreator({ endpoint: `${BLOG_PUBLIC_PREFIX}/${Modules.BlogCategory.name}` });
+  endpoint.addAdditionalParam("language", params.language);
+
+  const res = await ServerJsonApiGet({
+    classKey: { ...Modules.BlogCategory, cache: "minutes" },
+    endpoint: endpoint.generate(),
+    language: params.language,
+  });
+  if (!res.ok) return [];
+
+  return asArray<BlogCategoryInterface>(res.data).map(toPublicBlogCategory);
+}
+
+export async function fetchBlogSettings(): Promise<{ listLayout: BlogListLayout }> {
+  const fallback: { listLayout: BlogListLayout } = { listLayout: "featured" };
+
+  // The settings are language-neutral; the language only fills the required
+  // request header, so one fixed value keeps a single cache entry.
+  const res = await ServerJsonApiGet({
+    classKey: { ...Modules.BlogSettings, cache: "minutes" },
+    endpoint: new EndpointCreator({ endpoint: `${BLOG_PUBLIC_PREFIX}/${Modules.BlogSettings.name}` }).generate(),
+    language: "en",
+  });
+  if (!res.ok) return fallback;
+
+  const settings = asArray<BlogSettingsInterface>(res.data)[0];
+  if (!settings || !BLOG_LIST_LAYOUTS.includes(settings.listLayout)) return fallback;
+
+  return { listLayout: settings.listLayout };
+}

package/src/features/blog/server/toPublic.spec.ts

@@ -0,0 +1,91 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { User } from "../../user/data/user";
+import { ModuleRegistry } from "../../../core/registry/ModuleRegistry";
+import { ModuleFactory, ModuleWithPermissions } from "../../../permissions/types";
+import {
+  BlogCategoryModule,
+  BlogCategoryTranslationModule,
+  BlogPostModule,
+  BlogPostTranslationModule,
+} from "../BlogModules";
+import { BlogCategory } from "../data/BlogCategory";
+import { BlogPost } from "../data/BlogPost";
+import { toPublicBlogCategory, toPublicBlogPost } from "./toPublic";
+
+const moduleFactory: ModuleFactory = (params) =>
+  ({
+    pageUrl: params.pageUrl,
+    name: params.name,
+    model: params.model,
+  }) as ModuleWithPermissions;
+
+beforeAll(() => {
+  ModuleRegistry.register("BlogPost", BlogPostModule(moduleFactory));
+  ModuleRegistry.register("BlogPostTranslation", BlogPostTranslationModule(moduleFactory));
+  ModuleRegistry.register("BlogCategory", BlogCategoryModule(moduleFactory));
+  ModuleRegistry.register("BlogCategoryTranslation", BlogCategoryTranslationModule(moduleFactory));
+  ModuleRegistry.register("User", { name: "users", model: User } as ModuleWithPermissions);
+});
+
+const blocks = [{ type: "paragraph", content: [{ type: "text", text: "Hello", styles: {} }] }];
+
+const makePost = () =>
+  new BlogPost().rehydrate({
+    jsonApi: {
+      id: "p",
+      type: "blog-posts",
+      attributes: {
+        status: "published",
+        originalLanguage: "en",
+        publishedAt: "2026-10-12T09:00:00.000Z",
+        language: "en",
+        title: "Prep situations",
+        slug: "prep-situations",
+        summary: "What to prepare.",
+        body: JSON.stringify(blocks),
+        readingMinutes: 4,
+        authorName: "Ada",
+        categoryIds: ["c1"],
+      },
+      meta: { createdAt: "2026-10-10T09:00:00.000Z", updatedAt: "2026-10-14T09:00:00.000Z" },
+    },
+    included: [],
+  } as any);
+
+describe("toPublicBlogPost", () => {
+  it("toPublicBlogPost maps a rehydrated post to plain serialisable data", () => {
+    expect(JSON.parse(JSON.stringify(toPublicBlogPost(makePost())))).toEqual(toPublicBlogPost(makePost()));
+    expect(toPublicBlogPost(makePost()).publishedAt).toBe("2026-10-12T09:00:00.000Z");
+  });
+
+  it("carries the resolved fields", () => {
+    const result = toPublicBlogPost(makePost());
+    expect(result).toMatchObject({
+      id: "p",
+      language: "en",
+      title: "Prep situations",
+      slug: "prep-situations",
+      summary: "What to prepare.",
+      readingMinutes: 4,
+      updatedAt: "2026-10-14T09:00:00.000Z",
+      authorName: "Ada",
+      categoryIds: ["c1"],
+    });
+    expect(result.body).toEqual(blocks);
+  });
+});
+
+describe("toPublicBlogCategory", () => {
+  it("maps the resolved name and slug", () => {
+    const category = new BlogCategory().rehydrate({
+      jsonApi: {
+        id: "c1",
+        type: "blog-categories",
+        attributes: { originalLanguage: "en", name: "Game prep", slug: "game-prep" },
+      },
+      included: [],
+    } as any);
+
+    expect(toPublicBlogCategory(category)).toEqual({ id: "c1", name: "Game prep", slug: "game-prep" });
+  });
+});

package/src/features/blog/server/toPublic.ts

@@ -0,0 +1,36 @@
+import { BlogCategoryInterface } from "../data/BlogCategoryInterface";
+import { BlogPostInterface } from "../data/BlogPostInterface";
+import { PublicBlogCategory, PublicBlogPost } from "../types/blog-public.types";
+
+// Serialisation boundary: a rehydrated model (class instance, Date getters)
+// becomes plain data a server page can pass to the public client components.
+
+export function toPublicBlogPost(post: BlogPostInterface): PublicBlogPost {
+  const publishedAt = post.publishedAt ?? post.createdAt;
+
+  return {
+    id: post.id,
+    language: post.language ?? post.originalLanguage,
+    title: post.title ?? "",
+    slug: post.slug ?? "",
+    summary: post.summary,
+    body: post.body,
+    coverImage: post.coverImage,
+    coverImageAlt: post.coverImageAlt,
+    readingMinutes: post.readingMinutes ?? 1,
+    publishedAt: publishedAt.toISOString(),
+    updatedAt: post.updatedAt.toISOString(),
+    authorName: post.authorName,
+    categoryIds: [...post.categoryIds],
+  };
+}
+
+export function toPublicBlogCategory(category: BlogCategoryInterface): PublicBlogCategory {
+  return {
+    id: category.id,
+    name: category.name ?? "",
+    slug: category.slug ?? "",
+    description: category.description,
+    image: category.image,
+  };
+}

package/src/features/blog/server-entry.ts

@@ -0,0 +1,17 @@
+// Server-safe public barrel for the blog feature.
+// Consumed via `@carlonicora/nextjs-jsonapi/blog/server`. Must NOT receive a
+// "use client" directive: server pages import the cached public fetchers and
+// the plain view-model types from here without pulling the client bundle.
+// Client components live in `@carlonicora/nextjs-jsonapi/blog`.
+
+export {
+  fetchBlogSettings,
+  fetchPublicBlogCategories,
+  fetchPublicBlogPost,
+  fetchPublicBlogPosts,
+  fetchRelatedBlogPosts,
+} from "./server/fetchers";
+export { toPublicBlogCategory, toPublicBlogPost } from "./server/toPublic";
+export { BLOG_LIST_LAYOUTS } from "./types/blog.constants";
+export type { BlogListLayout } from "./types/blog.constants";
+export type { PublicBlogCategory, PublicBlogList, PublicBlogPost } from "./types/blog-public.types";