@carlonicora/nextjs-jsonapi 5.2.0 → 5.4.0

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

@@ -0,0 +1,39 @@
+import { ApiDataInterface } from "../../../core";
+import { UserInterface } from "../../user/data/user.interface";
+import { BlogPostStatus } from "../types/blog.constants";
+import { BlogCategoryInterface } from "./BlogCategoryInterface";
+import { BlogPostTranslationInterface } from "./BlogPostTranslationInterface";
+
+export type BlogPostInput = {
+  id: string;
+  originalLanguage?: string;
+  title?: string;
+  slug?: string;
+  summary?: string;
+  body?: any;
+  coverImage?: string;
+  coverImageAlt?: string;
+  categoryIds?: string[];
+};
+
+export interface BlogPostInterface extends ApiDataInterface {
+  get status(): BlogPostStatus;
+  get originalLanguage(): string;
+  get coverImage(): string | undefined;
+  get publishedAt(): Date | undefined;
+  get author(): UserInterface | undefined;
+  get categories(): BlogCategoryInterface[];
+  get translations(): BlogPostTranslationInterface[];
+  get original(): BlogPostTranslationInterface | undefined;
+
+  // Resolved for one language by the public and list queries.
+  get language(): string | undefined;
+  get title(): string | undefined;
+  get slug(): string | undefined;
+  get summary(): string | undefined;
+  get body(): any;
+  get coverImageAlt(): string | undefined;
+  get readingMinutes(): number | undefined;
+  get authorName(): string | undefined;
+  get categoryIds(): string[];
+}

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

@@ -0,0 +1,82 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules, NextRef } from "../../../core";
+import { BLOG_ACTION } from "../types/blog.constants";
+import { BlogPostInput, BlogPostInterface } from "./BlogPostInterface";
+
+export class BlogPostService extends AbstractService {
+  static async findMany(params: { search?: string; next?: NextRef } = {}): Promise<BlogPostInterface[]> {
+    const endpoint = new EndpointCreator({ endpoint: Modules.BlogPost });
+
+    if (params.search) endpoint.addAdditionalParam("search", params.search);
+
+    return this.callApi<BlogPostInterface[]>({
+      type: Modules.BlogPost,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+      next: params.next,
+    });
+  }
+
+  static async findOne(params: { id: string }): Promise<BlogPostInterface> {
+    return this.callApi<BlogPostInterface>({
+      type: Modules.BlogPost,
+      method: HttpMethod.GET,
+      endpoint: new EndpointCreator({ endpoint: Modules.BlogPost, id: params.id }).generate(),
+    });
+  }
+
+  static async create(params: BlogPostInput): Promise<BlogPostInterface> {
+    return this.callApi<BlogPostInterface>({
+      type: Modules.BlogPost,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({ endpoint: Modules.BlogPost }).generate(),
+      input: params,
+    });
+  }
+
+  static async update(params: BlogPostInput): Promise<BlogPostInterface> {
+    return this.callApi<BlogPostInterface>({
+      type: Modules.BlogPost,
+      method: HttpMethod.PUT,
+      endpoint: new EndpointCreator({ endpoint: Modules.BlogPost, id: params.id }).generate(),
+      input: params,
+    });
+  }
+
+  static async delete(params: { id: string }): Promise<void> {
+    await this.callApi({
+      type: Modules.BlogPost,
+      method: HttpMethod.DELETE,
+      endpoint: new EndpointCreator({ endpoint: Modules.BlogPost, id: params.id }).generate(),
+    });
+  }
+
+  /**
+   * POST blog-posts/:id/publish. Sends no body; replies with the post.
+   */
+  static async publish(params: { id: string }): Promise<BlogPostInterface> {
+    return this.callApi<BlogPostInterface>({
+      type: Modules.BlogPost,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({
+        endpoint: Modules.BlogPost,
+        id: params.id,
+        childEndpoint: BLOG_ACTION.publish,
+      }).generate(),
+    });
+  }
+
+  /**
+   * POST blog-posts/:id/unpublish. Sends no body; replies with the post.
+   */
+  static async unpublish(params: { id: string }): Promise<BlogPostInterface> {
+    return this.callApi<BlogPostInterface>({
+      type: Modules.BlogPost,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({
+        endpoint: Modules.BlogPost,
+        id: params.id,
+        childEndpoint: BLOG_ACTION.unpublish,
+      }).generate(),
+    });
+  }
+}

package/src/features/blog/data/BlogPostTranslation.spec.ts

@@ -0,0 +1,73 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { ModuleRegistry } from "../../../core/registry/ModuleRegistry";
+import { ModuleFactory, ModuleWithPermissions } from "../../../permissions/types";
+import { BlogPostModule, BlogPostTranslationModule } from "../BlogModules";
+import { BlogPostTranslation } from "./BlogPostTranslation";
+
+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));
+});
+
+const blocks = [{ type: "paragraph", content: [{ type: "text", text: "Ciao", styles: {} }] }];
+
+describe("BlogPostTranslation", () => {
+  it("BlogPostTranslation.rehydrate exposes source, aiStatus and translatedAt as Date", () => {
+    const translation = new BlogPostTranslation().rehydrate({
+      jsonApi: {
+        id: "t",
+        type: "blog-post-translations",
+        attributes: {
+          language: "it",
+          isOriginal: false,
+          source: "manual",
+          aiStatus: "completed",
+          title: "Titolo",
+          slug: "titolo",
+          body: JSON.stringify(blocks),
+          readingMinutes: 2,
+          translatedAt: "2026-10-12T09:00:00.000Z",
+        },
+      },
+      included: [],
+    } as any);
+
+    expect(translation.language).toBe("it");
+    expect(translation.isOriginal).toBe(false);
+    expect(translation.source).toBe("manual");
+    expect(translation.aiStatus).toBe("completed");
+    expect(translation.translatedAt).toBeInstanceOf(Date);
+    expect(translation.translatedAt?.toISOString()).toBe("2026-10-12T09:00:00.000Z");
+    expect(translation.body).toEqual(blocks);
+    expect(translation.readingMinutes).toBe(2);
+  });
+
+  it("a pending placeholder has no text and no translatedAt", () => {
+    const translation = new BlogPostTranslation().rehydrate({
+      jsonApi: {
+        id: "t",
+        type: "blog-post-translations",
+        attributes: { language: "it", isOriginal: false, source: "ai", aiStatus: "pending" },
+      },
+      included: [],
+    } as any);
+
+    expect(translation.aiStatus).toBe("pending");
+    expect(translation.title).toBe("");
+    expect(translation.body).toEqual([]);
+    expect(translation.translatedAt).toBeUndefined();
+  });
+
+  it("createJsonApi stringifies the body and sends only the editable fields", () => {
+    const payload = new BlogPostTranslation().createJsonApi({ id: "t", title: "Titolo", body: blocks });
+    expect(payload.data.type).toBe("blog-post-translations");
+    expect(payload.data.attributes).toEqual({ title: "Titolo", body: JSON.stringify(blocks) });
+  });
+});

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

@@ -0,0 +1,110 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { BlogAiStatus, BlogTranslationSource } from "../types/blog.constants";
+import { BlogPostInterface } from "./BlogPostInterface";
+import { BlogPostTranslationInput, BlogPostTranslationInterface } from "./BlogPostTranslationInterface";
+
+export class BlogPostTranslation extends AbstractApiData implements BlogPostTranslationInterface {
+  private _language?: string;
+  private _isOriginal?: boolean;
+  private _source?: BlogTranslationSource;
+  private _aiStatus?: BlogAiStatus;
+  private _title?: string;
+  private _slug?: string;
+  private _summary?: string;
+  private _body?: any;
+  private _coverImageAlt?: string;
+  private _readingMinutes?: number;
+  private _translatedAt?: Date;
+  private _post?: BlogPostInterface;
+
+  get language(): string {
+    return this._language ?? "";
+  }
+
+  get isOriginal(): boolean {
+    return this._isOriginal ?? false;
+  }
+
+  get source(): BlogTranslationSource {
+    return this._source ?? "ai";
+  }
+
+  get aiStatus(): BlogAiStatus {
+    return this._aiStatus ?? "pending";
+  }
+
+  get title(): string {
+    return this._title ?? "";
+  }
+
+  get slug(): string {
+    return this._slug ?? "";
+  }
+
+  get summary(): string | undefined {
+    return this._summary;
+  }
+
+  get body(): any {
+    return this._body ?? [];
+  }
+
+  get coverImageAlt(): string | undefined {
+    return this._coverImageAlt;
+  }
+
+  get readingMinutes(): number {
+    return this._readingMinutes ?? 1;
+  }
+
+  get translatedAt(): Date | undefined {
+    return this._translatedAt;
+  }
+
+  get post(): BlogPostInterface | undefined {
+    return this._post;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attributes = data.jsonApi.attributes ?? {};
+
+    this._language = attributes.language;
+    this._isOriginal = attributes.isOriginal === true;
+    this._source = attributes.source;
+    this._aiStatus = attributes.aiStatus;
+    this._title = attributes.title ?? undefined;
+    this._slug = attributes.slug ?? undefined;
+    this._summary = attributes.summary ?? undefined;
+    this._body = attributes.body ? JSON.parse(attributes.body) : undefined;
+    this._coverImageAlt = attributes.coverImageAlt ?? undefined;
+    this._readingMinutes = attributes.readingMinutes ?? undefined;
+    this._translatedAt = attributes.translatedAt ? new Date(attributes.translatedAt) : undefined;
+
+    this._post = this._readIncluded(data, "post", Modules.BlogPost) as BlogPostInterface;
+
+    return this;
+  }
+
+  createJsonApi(data: BlogPostTranslationInput) {
+    const response: any = {
+      data: {
+        type: Modules.BlogPostTranslation.name,
+        id: data.id,
+        attributes: {},
+        meta: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    if (data.title !== undefined) response.data.attributes.title = data.title;
+    if (data.slug !== undefined) response.data.attributes.slug = data.slug;
+    if (data.summary !== undefined) response.data.attributes.summary = data.summary;
+    if (data.body !== undefined) response.data.attributes.body = JSON.stringify(data.body);
+    if (data.coverImageAlt !== undefined) response.data.attributes.coverImageAlt = data.coverImageAlt;
+
+    return response;
+  }
+}

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

@@ -0,0 +1,27 @@
+import { ApiDataInterface } from "../../../core";
+import { BlogAiStatus, BlogTranslationSource } from "../types/blog.constants";
+import { BlogPostInterface } from "./BlogPostInterface";
+
+export type BlogPostTranslationInput = {
+  id: string;
+  title?: string;
+  slug?: string;
+  summary?: string;
+  body?: any;
+  coverImageAlt?: string;
+};
+
+export interface BlogPostTranslationInterface extends ApiDataInterface {
+  get language(): string;
+  get isOriginal(): boolean;
+  get source(): BlogTranslationSource;
+  get aiStatus(): BlogAiStatus;
+  get title(): string;
+  get slug(): string;
+  get summary(): string | undefined;
+  get body(): any;
+  get coverImageAlt(): string | undefined;
+  get readingMinutes(): number;
+  get translatedAt(): Date | undefined;
+  get post(): BlogPostInterface | undefined;
+}

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);