@carlonicora/nextjs-jsonapi 5.2.0 → 5.4.0

package/src/features/blog/contexts/BlogPostContext.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+import { createContext, ReactNode, useCallback, useContext, useEffect, useMemo, useState } from "react";
+import { BlogPostInterface, BlogPostService } from "../data";
+
+/** How often the post page re-reads the post while a translation job runs. */
+const TRANSLATION_POLL_MS = 5000;
+
+export interface BlogPostContextType {
+  post: BlogPostInterface | undefined;
+  reload: () => Promise<void>;
+}
+
+const BlogPostContext = createContext<BlogPostContextType | undefined>(undefined);
+
+export type BlogPostProviderProps = {
+  postId: string;
+  children: ReactNode;
+};
+
+/**
+ * Loads one post (with its translations, categories and author) for the admin
+ * post page. While any translation is `pending` or `in_progress` it re-reads
+ * the post every 5 s, so the language tabs move from "Translating…" to the
+ * translated text without a manual refresh; it stops once none are running.
+ */
+export const BlogPostProvider = ({ postId, children }: BlogPostProviderProps) => {
+  const [post, setPost] = useState<BlogPostInterface | undefined>(undefined);
+
+  const reload = useCallback(async () => {
+    const loaded = await BlogPostService.findOne({ id: postId });
+    setPost(loaded);
+  }, [postId]);
+
+  useEffect(() => {
+    void reload();
+  }, [reload]);
+
+  const isTranslating = useMemo(
+    () =>
+      (post?.translations ?? []).some(
+        (translation) => translation.aiStatus === "pending" || translation.aiStatus === "in_progress",
+      ),
+    [post],
+  );
+
+  useEffect(() => {
+    if (!isTranslating) return;
+    const handle = setInterval(() => {
+      reload().catch(() => {});
+    }, TRANSLATION_POLL_MS);
+    return () => clearInterval(handle);
+  }, [isTranslating, reload]);
+
+  const value = useMemo<BlogPostContextType>(() => ({ post, reload }), [post, reload]);
+
+  return <BlogPostContext.Provider value={value}>{children}</BlogPostContext.Provider>;
+};
+
+export const useBlogPost = (): BlogPostContextType => {
+  const context = useContext(BlogPostContext);
+  if (context === undefined) {
+    throw new Error("useBlogPost must be used within a BlogPostProvider");
+  }
+  return context;
+};

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

@@ -0,0 +1 @@
+export * from "./BlogPostContext";

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

@@ -0,0 +1,93 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { BlogCategoryInput, BlogCategoryInterface } from "./BlogCategoryInterface";
+import { BlogCategoryTranslationInterface } from "./BlogCategoryTranslationInterface";
+
+export class BlogCategory extends AbstractApiData implements BlogCategoryInterface {
+  private _originalLanguage?: string;
+  private _image?: string;
+  private _translations?: BlogCategoryTranslationInterface[];
+
+  private _language?: string;
+  private _name?: string;
+  private _slug?: string;
+  private _description?: string;
+
+  get originalLanguage(): string {
+    return this._originalLanguage ?? "";
+  }
+
+  get image(): string | undefined {
+    return this._image;
+  }
+
+  get translations(): BlogCategoryTranslationInterface[] {
+    return this._translations ?? [];
+  }
+
+  get original(): BlogCategoryTranslationInterface | undefined {
+    return this.translations.find((translation) => translation.isOriginal);
+  }
+
+  get language(): string | undefined {
+    return this._language;
+  }
+
+  get name(): string | undefined {
+    return this._name;
+  }
+
+  get slug(): string | undefined {
+    return this._slug;
+  }
+
+  get description(): string | undefined {
+    return this._description;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attributes = data.jsonApi.attributes ?? {};
+    const meta = data.jsonApi.meta ?? {};
+    // The resolved-language values are computed on the API. Depending on the
+    // descriptor they arrive as attributes or as meta, so both are read.
+    const resolved = (key: string) => attributes[key] ?? meta[key] ?? undefined;
+
+    this._originalLanguage = attributes.originalLanguage;
+    this._image = attributes.image ?? undefined;
+
+    this._language = resolved("language");
+    this._name = resolved("name");
+    this._slug = resolved("slug");
+    this._description = resolved("description");
+
+    this._translations = this._readIncluded(
+      data,
+      "translations",
+      Modules.BlogCategoryTranslation,
+    ) as BlogCategoryTranslationInterface[];
+
+    return this;
+  }
+
+  createJsonApi(data: BlogCategoryInput) {
+    const response: any = {
+      data: {
+        type: Modules.BlogCategory.name,
+        id: data.id,
+        attributes: {},
+        meta: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    if (data.originalLanguage !== undefined) response.data.attributes.originalLanguage = data.originalLanguage;
+    if (data.name !== undefined) response.data.attributes.name = data.name;
+    if (data.slug !== undefined) response.data.attributes.slug = data.slug;
+    if (data.description !== undefined) response.data.attributes.description = data.description;
+    if (data.image !== undefined) response.data.attributes.image = data.image;
+
+    return response;
+  }
+}

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

@@ -0,0 +1,4 @@
+export enum BlogCategoryFields {
+  name = "name",
+  languages = "languages",
+}

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

@@ -0,0 +1,24 @@
+import { ApiDataInterface } from "../../../core";
+import { BlogCategoryTranslationInterface } from "./BlogCategoryTranslationInterface";
+
+export type BlogCategoryInput = {
+  id: string;
+  originalLanguage?: string;
+  name?: string;
+  slug?: string;
+  description?: string;
+  image?: string;
+};
+
+export interface BlogCategoryInterface extends ApiDataInterface {
+  get originalLanguage(): string;
+  get image(): string | undefined;
+  get translations(): BlogCategoryTranslationInterface[];
+  get original(): BlogCategoryTranslationInterface | undefined;
+
+  // Resolved for one language by the public and list queries.
+  get language(): string | undefined;
+  get name(): string | undefined;
+  get slug(): string | undefined;
+  get description(): string | undefined;
+}

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

@@ -0,0 +1,54 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules, NextRef } from "../../../core";
+import { BlogCategoryInput, BlogCategoryInterface } from "./BlogCategoryInterface";
+
+export class BlogCategoryService extends AbstractService {
+  static async findMany(
+    params: { search?: string; fetchAll?: boolean; next?: NextRef } = {},
+  ): Promise<BlogCategoryInterface[]> {
+    const endpoint = new EndpointCreator({ endpoint: Modules.BlogCategory });
+
+    if (params.fetchAll) endpoint.addAdditionalParam("fetchAll", "true");
+    if (params.search) endpoint.addAdditionalParam("search", params.search);
+
+    return this.callApi<BlogCategoryInterface[]>({
+      type: Modules.BlogCategory,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+      next: params.next,
+    });
+  }
+
+  static async findOne(params: { id: string }): Promise<BlogCategoryInterface> {
+    return this.callApi<BlogCategoryInterface>({
+      type: Modules.BlogCategory,
+      method: HttpMethod.GET,
+      endpoint: new EndpointCreator({ endpoint: Modules.BlogCategory, id: params.id }).generate(),
+    });
+  }
+
+  static async create(params: BlogCategoryInput): Promise<BlogCategoryInterface> {
+    return this.callApi<BlogCategoryInterface>({
+      type: Modules.BlogCategory,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({ endpoint: Modules.BlogCategory }).generate(),
+      input: params,
+    });
+  }
+
+  static async update(params: BlogCategoryInput): Promise<BlogCategoryInterface> {
+    return this.callApi<BlogCategoryInterface>({
+      type: Modules.BlogCategory,
+      method: HttpMethod.PUT,
+      endpoint: new EndpointCreator({ endpoint: Modules.BlogCategory, id: params.id }).generate(),
+      input: params,
+    });
+  }
+
+  static async delete(params: { id: string }): Promise<void> {
+    await this.callApi({
+      type: Modules.BlogCategory,
+      method: HttpMethod.DELETE,
+      endpoint: new EndpointCreator({ endpoint: Modules.BlogCategory, id: params.id }).generate(),
+    });
+  }
+}

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

@@ -0,0 +1,90 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { BlogAiStatus, BlogTranslationSource } from "../types/blog.constants";
+import { BlogCategoryInterface } from "./BlogCategoryInterface";
+import { BlogCategoryTranslationInput, BlogCategoryTranslationInterface } from "./BlogCategoryTranslationInterface";
+
+export class BlogCategoryTranslation extends AbstractApiData implements BlogCategoryTranslationInterface {
+  private _language?: string;
+  private _isOriginal?: boolean;
+  private _source?: BlogTranslationSource;
+  private _aiStatus?: BlogAiStatus;
+  private _name?: string;
+  private _slug?: string;
+  private _description?: string;
+  private _translatedAt?: Date;
+  private _category?: BlogCategoryInterface;
+
+  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 name(): string {
+    return this._name ?? "";
+  }
+
+  get slug(): string {
+    return this._slug ?? "";
+  }
+
+  get description(): string | undefined {
+    return this._description;
+  }
+
+  get translatedAt(): Date | undefined {
+    return this._translatedAt;
+  }
+
+  get category(): BlogCategoryInterface | undefined {
+    return this._category;
+  }
+
+  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._name = attributes.name ?? undefined;
+    this._slug = attributes.slug ?? undefined;
+    this._description = attributes.description ?? undefined;
+    this._translatedAt = attributes.translatedAt ? new Date(attributes.translatedAt) : undefined;
+
+    this._category = this._readIncluded(data, "category", Modules.BlogCategory) as BlogCategoryInterface;
+
+    return this;
+  }
+
+  createJsonApi(data: BlogCategoryTranslationInput) {
+    const response: any = {
+      data: {
+        type: Modules.BlogCategoryTranslation.name,
+        id: data.id,
+        attributes: {},
+        meta: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    if (data.name !== undefined) response.data.attributes.name = data.name;
+    if (data.slug !== undefined) response.data.attributes.slug = data.slug;
+    if (data.description !== undefined) response.data.attributes.description = data.description;
+
+    return response;
+  }
+}

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

@@ -0,0 +1,22 @@
+import { ApiDataInterface } from "../../../core";
+import { BlogAiStatus, BlogTranslationSource } from "../types/blog.constants";
+import { BlogCategoryInterface } from "./BlogCategoryInterface";
+
+export type BlogCategoryTranslationInput = {
+  id: string;
+  name?: string;
+  slug?: string;
+  description?: string;
+};
+
+export interface BlogCategoryTranslationInterface extends ApiDataInterface {
+  get language(): string;
+  get isOriginal(): boolean;
+  get source(): BlogTranslationSource;
+  get aiStatus(): BlogAiStatus;
+  get name(): string;
+  get slug(): string;
+  get description(): string | undefined;
+  get translatedAt(): Date | undefined;
+  get category(): BlogCategoryInterface | undefined;
+}

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

@@ -0,0 +1,30 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules } from "../../../core";
+import { BLOG_ACTION } from "../types/blog.constants";
+import { BlogCategoryTranslationInput, BlogCategoryTranslationInterface } from "./BlogCategoryTranslationInterface";
+
+export class BlogCategoryTranslationService extends AbstractService {
+  static async update(params: BlogCategoryTranslationInput): Promise<BlogCategoryTranslationInterface> {
+    return this.callApi<BlogCategoryTranslationInterface>({
+      type: Modules.BlogCategoryTranslation,
+      method: HttpMethod.PUT,
+      endpoint: new EndpointCreator({ endpoint: Modules.BlogCategoryTranslation, id: params.id }).generate(),
+      input: params,
+    });
+  }
+
+  /**
+   * POST blog-category-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.BlogCategoryTranslation,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({
+        endpoint: Modules.BlogCategoryTranslation,
+        id: params.id,
+        childEndpoint: BLOG_ACTION.retranslate,
+      }).generate(),
+    });
+  }
+}

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

@@ -0,0 +1,123 @@
+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,
+  BlogSettingsModule,
+} from "../BlogModules";
+import { BlogPost } from "./BlogPost";
+import { BlogPostTranslation } from "./BlogPostTranslation";
+import { BlogCategory } from "./BlogCategory";
+import { DataClassRegistry } from "../../../core/registry/DataClassRegistry";
+import { Modules } from "../../../core/registry/ModuleRegistry";
+
+// createJsonApi reads Modules.X.name (resolved lazily via ModuleRegistry), so
+// the modules must be registered before a model serialises — mirrors the
+// email-automation-models.spec setup convention in this package.
+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("BlogSettings", BlogSettingsModule(moduleFactory));
+  ModuleRegistry.register("User", { name: "users", model: User } as ModuleWithPermissions);
+  DataClassRegistry.registerObjectClass(Modules.BlogPostTranslation, BlogPostTranslation);
+  DataClassRegistry.registerObjectClass(Modules.BlogCategory, BlogCategory);
+  DataClassRegistry.registerObjectClass(Modules.User, User);
+});
+
+const blocks = [{ type: "paragraph", content: [{ type: "text", text: "Hello", styles: {} }] }];
+
+describe("BlogPost", () => {
+  it("BlogPost.createJsonApi stringifies the body and sends categories", () => {
+    const p = new BlogPost().createJsonApi({
+      id: "p",
+      originalLanguage: "en",
+      title: "T",
+      body: [{ type: "paragraph" }],
+      categoryIds: ["c1"],
+    });
+    expect(p.data.type).toBe("blog-posts");
+    expect(typeof p.data.attributes.body).toBe("string");
+    expect(JSON.parse(p.data.attributes.body)).toEqual([{ type: "paragraph" }]);
+    expect(p.data.relationships.categories.data).toEqual([{ type: "blog-categories", id: "c1" }]);
+  });
+
+  it("never sends server-owned attributes", () => {
+    const p = new BlogPost().createJsonApi({ id: "p", title: "T" });
+    expect(p.data.attributes).toEqual({ title: "T" });
+    expect("categories" in p.data.relationships).toBe(false);
+  });
+
+  it("BlogPost.rehydrate parses publishedAt as a Date and the resolved body as blocks", () => {
+    const post = new BlogPost().rehydrate({
+      jsonApi: {
+        id: "p",
+        type: "blog-posts",
+        attributes: {
+          status: "published",
+          originalLanguage: "en",
+          publishedAt: "2026-10-12T09:00:00.000Z",
+          language: "it",
+          title: "Titolo",
+          slug: "titolo",
+          body: JSON.stringify(blocks),
+          readingMinutes: 3,
+          authorName: "Ada",
+          categoryIds: ["c1"],
+        },
+        relationships: {
+          translations: { data: [{ type: "blog-post-translations", id: "t1" }] },
+        },
+      },
+      included: [
+        {
+          id: "t1",
+          type: "blog-post-translations",
+          attributes: { language: "en", isOriginal: true, source: "original", aiStatus: "completed", title: "Title" },
+        },
+      ],
+    } as any);
+
+    expect(post.publishedAt).toBeInstanceOf(Date);
+    expect(post.publishedAt?.toISOString()).toBe("2026-10-12T09:00:00.000Z");
+    expect(Array.isArray(post.body)).toBe(true);
+    expect(post.body).toEqual(blocks);
+    expect(post.status).toBe("published");
+    expect(post.language).toBe("it");
+    expect(post.title).toBe("Titolo");
+    expect(post.readingMinutes).toBe(3);
+    expect(post.authorName).toBe("Ada");
+    expect(post.categoryIds).toEqual(["c1"]);
+    expect(post.translations).toHaveLength(1);
+    expect(post.original?.title).toBe("Title");
+  });
+
+  it("reads resolved values sent as meta", () => {
+    const post = new BlogPost().rehydrate({
+      jsonApi: {
+        id: "p",
+        type: "blog-posts",
+        attributes: { status: "draft", originalLanguage: "en" },
+        meta: { title: "From meta", categoryIds: ["c2"] },
+      },
+      included: [],
+    } as any);
+
+    expect(post.title).toBe("From meta");
+    expect(post.categoryIds).toEqual(["c2"]);
+    expect(post.publishedAt).toBeUndefined();
+    expect(post.body).toEqual([]);
+  });
+});

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

@@ -0,0 +1,159 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { UserInterface } from "../../user/data/user.interface";
+import { BlogPostStatus } from "../types/blog.constants";
+import { BlogCategoryInterface } from "./BlogCategoryInterface";
+import { BlogPostInput, BlogPostInterface } from "./BlogPostInterface";
+import { BlogPostTranslationInterface } from "./BlogPostTranslationInterface";
+
+export class BlogPost extends AbstractApiData implements BlogPostInterface {
+  private _status?: BlogPostStatus;
+  private _originalLanguage?: string;
+  private _coverImage?: string;
+  private _publishedAt?: Date;
+  private _author?: UserInterface;
+  private _categories?: BlogCategoryInterface[];
+  private _translations?: BlogPostTranslationInterface[];
+
+  private _language?: string;
+  private _title?: string;
+  private _slug?: string;
+  private _summary?: string;
+  private _body?: any;
+  private _coverImageAlt?: string;
+  private _readingMinutes?: number;
+  private _authorName?: string;
+  private _categoryIds?: string[];
+
+  get status(): BlogPostStatus {
+    return this._status ?? "draft";
+  }
+
+  get originalLanguage(): string {
+    return this._originalLanguage ?? "";
+  }
+
+  get coverImage(): string | undefined {
+    return this._coverImage;
+  }
+
+  get publishedAt(): Date | undefined {
+    return this._publishedAt;
+  }
+
+  get author(): UserInterface | undefined {
+    return this._author;
+  }
+
+  get categories(): BlogCategoryInterface[] {
+    return this._categories ?? [];
+  }
+
+  get translations(): BlogPostTranslationInterface[] {
+    return this._translations ?? [];
+  }
+
+  get original(): BlogPostTranslationInterface | undefined {
+    return this.translations.find((translation) => translation.isOriginal);
+  }
+
+  get language(): string | undefined {
+    return this._language;
+  }
+
+  get title(): string | undefined {
+    return this._title;
+  }
+
+  get slug(): string | undefined {
+    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 | undefined {
+    return this._readingMinutes;
+  }
+
+  get authorName(): string | undefined {
+    return this._authorName;
+  }
+
+  get categoryIds(): string[] {
+    return this._categoryIds ?? [];
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attributes = data.jsonApi.attributes ?? {};
+    const meta = data.jsonApi.meta ?? {};
+    // The resolved-language values are computed on the API. Depending on the
+    // descriptor they arrive as attributes or as meta, so both are read.
+    const resolved = (key: string) => attributes[key] ?? meta[key] ?? undefined;
+
+    this._status = attributes.status;
+    this._originalLanguage = attributes.originalLanguage;
+    this._coverImage = attributes.coverImage ?? undefined;
+    this._publishedAt = attributes.publishedAt ? new Date(attributes.publishedAt) : undefined;
+
+    this._language = resolved("language");
+    this._title = resolved("title");
+    this._slug = resolved("slug");
+    this._summary = resolved("summary");
+    const body = resolved("body");
+    this._body = body ? JSON.parse(body) : undefined;
+    this._coverImageAlt = resolved("coverImageAlt");
+    this._readingMinutes = resolved("readingMinutes");
+    this._authorName = resolved("authorName");
+    this._categoryIds = resolved("categoryIds") ?? [];
+
+    this._author = this._readIncluded(data, "author", Modules.User) as UserInterface;
+    this._categories = this._readIncluded(data, "categories", Modules.BlogCategory) as BlogCategoryInterface[];
+    this._translations = this._readIncluded(
+      data,
+      "translations",
+      Modules.BlogPostTranslation,
+    ) as BlogPostTranslationInterface[];
+
+    return this;
+  }
+
+  createJsonApi(data: BlogPostInput) {
+    const response: any = {
+      data: {
+        type: Modules.BlogPost.name,
+        id: data.id,
+        attributes: {},
+        meta: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    if (data.originalLanguage !== undefined) response.data.attributes.originalLanguage = data.originalLanguage;
+    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.coverImage !== undefined) response.data.attributes.coverImage = data.coverImage;
+    if (data.coverImageAlt !== undefined) response.data.attributes.coverImageAlt = data.coverImageAlt;
+
+    if (data.categoryIds !== undefined) {
+      response.data.relationships.categories = {
+        data: data.categoryIds.map((id) => ({ type: Modules.BlogCategory.name, id })),
+      };
+    }
+
+    return response;
+  }
+}

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

@@ -0,0 +1,7 @@
+export enum BlogPostFields {
+  title = "title",
+  status = "status",
+  categories = "categories",
+  publishedAt = "publishedAt",
+  languages = "languages",
+}