@carlonicora/nextjs-jsonapi 3.11.0 → 3.13.0

package/src/features/handbook/data/HandbookThreadService.ts

@@ -0,0 +1,86 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules, NextRef, PreviousRef } from "../../../core";
+import { HandbookThread } from "./HandbookThread";
+import { HandbookThreadInput, HandbookThreadInterface } from "./HandbookThreadInterface";
+
+export class HandbookThreadService extends AbstractService {
+  /**
+   * `next` / `prev` are not optional extras: `useDataListRetriever` drives
+   * pagination by handing the cursor back here, so a findMany that drops them
+   * renders exactly one page and no navigation, however many rows exist.
+   * Mirrors HowToService.findMany.
+   */
+  static async findMany(
+    params: {
+      search?: string;
+      fetchAll?: boolean;
+      next?: NextRef;
+      prev?: PreviousRef;
+    } = {},
+  ): Promise<HandbookThreadInterface[]> {
+    const endpoint = new EndpointCreator({ endpoint: Modules.HandbookThread });
+
+    if (params.fetchAll) endpoint.addAdditionalParam("fetchAll", "true");
+    if (params.search) endpoint.addAdditionalParam("search", params.search);
+    if (Modules.HandbookThread.inclusions?.lists?.fields)
+      endpoint.limitToFields(Modules.HandbookThread.inclusions.lists.fields);
+    if (Modules.HandbookThread.inclusions?.lists?.types)
+      endpoint.limitToType(Modules.HandbookThread.inclusions.lists.types);
+
+    return this.callApi({
+      type: Modules.HandbookThread,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+      next: params.next,
+    });
+  }
+
+  /** Returns the thread with its messages side-loaded — the sidebar's select. */
+  static async findOne(params: { id: string }): Promise<HandbookThreadInterface> {
+    return this.callApi<HandbookThreadInterface>({
+      type: Modules.HandbookThread,
+      method: HttpMethod.GET,
+      endpoint: new EndpointCreator({ endpoint: Modules.HandbookThread, id: params.id }).generate(),
+    });
+  }
+
+  /**
+   * Opens a thread with its first question. The response is the thread (title
+   * included); the messages are read back with `findOne`, because only the
+   * single-resource endpoint side-loads them.
+   *
+   * The API answers 400 when the installation has no usable AI configuration
+   * and 403 for a non-administrator; both reach the caller as a thrown error.
+   *
+   * `HandbookThreadInput.handbookPageId` scopes retrieval to one page. It rides
+   * through the model's `createJsonApi()`, exactly as `question` does — there is
+   * no `overridesJsonApiCreation` on this path.
+   */
+  static async create(params: HandbookThreadInput): Promise<HandbookThreadInterface> {
+    return this.callApi<HandbookThreadInterface>({
+      type: Modules.HandbookThread,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({ endpoint: Modules.HandbookThread }).generate(),
+      input: params,
+      suppressGlobalError: true,
+    });
+  }
+
+  static async rename(params: { id: string; title: string }): Promise<void> {
+    const thread = new HandbookThread();
+    await this.callApi({
+      type: Modules.HandbookThread,
+      method: HttpMethod.PATCH,
+      endpoint: new EndpointCreator({ endpoint: Modules.HandbookThread, id: params.id }).generate(),
+      input: thread.createRenameJsonApi({ id: params.id, title: params.title }),
+      overridesJsonApiCreation: true,
+    });
+  }
+
+  static async delete(params: { id: string }): Promise<void> {
+    await this.callApi({
+      type: Modules.HandbookThread,
+      method: HttpMethod.DELETE,
+      endpoint: new EndpointCreator({ endpoint: Modules.HandbookThread, id: params.id }).generate(),
+    });
+  }
+}

package/src/features/handbook/data/__tests__/HandbookThreadService.spec.ts

@@ -0,0 +1,112 @@
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { AbstractService } from "../../../../core/abstracts/AbstractService";
+import { ApiRequestDataTypeInterface } from "../../../../core/interfaces/ApiRequestDataTypeInterface";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import { HandbookThread } from "../HandbookThread";
+import { HandbookThreadMessage } from "../HandbookThreadMessage";
+import { HandbookThreadMessageService } from "../HandbookThreadMessageService";
+import { HandbookThreadService } from "../HandbookThreadService";
+
+// ModuleRegistry is backed by a globalThis symbol shared across test files in a
+// worker, hence the register-if-absent guard (same idiom as
+// Assistant.scope.spec.ts).
+const registerIfAbsent = (key: string, module: ApiRequestDataTypeInterface) => {
+  try {
+    ModuleRegistry.get(key as any);
+  } catch {
+    ModuleRegistry.register(key, module);
+  }
+};
+
+beforeAll(() => {
+  registerIfAbsent("HandbookThread", { name: "handbookthreads", model: HandbookThread } as any);
+  registerIfAbsent("HandbookThreadMessage", {
+    name: "handbookthreadmessages",
+    model: HandbookThreadMessage,
+  } as any);
+});
+
+// `callApi` is a protected static on AbstractService; the services inherit it,
+// so spying on the base class intercepts every call without touching the HTTP
+// layer.
+type CallApiParams = {
+  method: string;
+  endpoint: string;
+  input?: unknown;
+  next?: unknown;
+  overridesJsonApiCreation?: boolean;
+};
+const callApi = () => vi.spyOn(AbstractService as any, "callApi");
+const firstCall = (spy: ReturnType<typeof callApi>): CallApiParams => spy.mock.calls[0][0] as CallApiParams;
+
+describe("HandbookThreadService.findMany", () => {
+  beforeEach(() => vi.restoreAllMocks());
+
+  it("forwards the pagination cursor — `useDataListRetriever` pages through it", async () => {
+    const spy = callApi().mockResolvedValue([]);
+
+    await HandbookThreadService.findMany({ next: { next: "handbookthreads?page[cursor]=42" } });
+
+    expect(spy).toHaveBeenCalledWith(expect.objectContaining({ next: { next: "handbookthreads?page[cursor]=42" } }));
+  });
+
+  it("still calls with an undefined cursor on the first page", async () => {
+    const spy = callApi().mockResolvedValue([]);
+
+    await HandbookThreadService.findMany();
+
+    expect(spy).toHaveBeenCalledWith(expect.objectContaining({ next: undefined }));
+  });
+
+  it("passes search and fetchAll through to the endpoint", async () => {
+    const spy = callApi().mockResolvedValue([]);
+
+    await HandbookThreadService.findMany({ search: "cypher", fetchAll: true });
+
+    const endpoint = firstCall(spy).endpoint;
+    expect(endpoint).toContain("handbookthreads");
+    expect(endpoint).toContain("cypher");
+    expect(endpoint).toContain("fetchAll");
+  });
+});
+
+describe("HandbookThreadService mutations", () => {
+  beforeEach(() => vi.restoreAllMocks());
+
+  it("creates a thread from the question alone and lets the model build the envelope", async () => {
+    const spy = callApi().mockResolvedValue({});
+
+    await HandbookThreadService.create({ id: "client-1", question: "  " });
+
+    const call = firstCall(spy);
+    expect(call.method).toBe("POST");
+    expect(call.input).toEqual({ id: "client-1", question: "  " });
+    expect(call.overridesJsonApiCreation).toBeUndefined();
+  });
+
+  it("renames through the model's dedicated envelope, never a hand-built one", async () => {
+    const spy = callApi().mockResolvedValue(undefined);
+
+    await HandbookThreadService.rename({ id: "t1", title: "Filtri di azienda" });
+
+    const call = firstCall(spy);
+    expect(call.method).toBe("PATCH");
+    expect(call.input).toEqual(new HandbookThread().createRenameJsonApi({ id: "t1", title: "Filtri di azienda" }));
+  });
+});
+
+describe("HandbookThreadMessageService.ask", () => {
+  beforeEach(() => vi.restoreAllMocks());
+
+  it("posts the question to the thread's message collection", async () => {
+    const spy = callApi().mockResolvedValue(undefined);
+
+    await HandbookThreadMessageService.ask({ id: "m1", threadId: "t1", question: "Come funziona?" });
+
+    const call = firstCall(spy);
+    expect(call.method).toBe("POST");
+    expect(call.endpoint).toContain("handbookthreads/t1/handbookthreadmessages");
+    expect(call.input).toEqual({ id: "m1", question: "Come funziona?" });
+  });
+});

package/src/features/handbook/data/handbookDisplay.spec.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+import {
+  handbookPageContent,
+  handbookPageSummary,
+  handbookPageTitle,
+  handbookSectionSummary,
+  handbookSectionTitle,
+} from "./handbookDisplay";
+
+/**
+ * The one rule the whole feature depends on: indexed in English, shown
+ * translated, and nothing but the rendered words changes.
+ */
+describe("handbookDisplay", () => {
+  describe("a page with a translation", () => {
+    const page = {
+      title: "Module anatomy",
+      displayTitle: "Anatomia di un modulo",
+      summary: "What a feature module contains.",
+      displaySummary: "Cosa contiene un modulo.",
+      content: "# Module anatomy\n",
+      displayContent: "# Anatomia di un modulo\n",
+    };
+
+    it("renders the translated title", () => {
+      expect(handbookPageTitle(page)).toBe("Anatomia di un modulo");
+    });
+
+    it("renders the translated summary", () => {
+      expect(handbookPageSummary(page)).toBe("Cosa contiene un modulo.");
+    });
+
+    it("renders the translated body", () => {
+      expect(handbookPageContent(page)).toBe("# Anatomia di un modulo\n");
+    });
+  });
+
+  describe("a page without a translation", () => {
+    const page = {
+      title: "Module anatomy",
+      displayTitle: undefined,
+      summary: "What a feature module contains.",
+      displaySummary: undefined,
+      content: "# Module anatomy\n",
+      displayContent: undefined,
+    };
+
+    it("falls back to the English title", () => {
+      expect(handbookPageTitle(page)).toBe("Module anatomy");
+    });
+
+    it("falls back to the English summary", () => {
+      expect(handbookPageSummary(page)).toBe("What a feature module contains.");
+    });
+
+    it("falls back to the English body", () => {
+      expect(handbookPageContent(page)).toBe("# Module anatomy\n");
+    });
+
+    it("leaves a summary that exists in neither language undefined", () => {
+      expect(handbookPageSummary({ summary: undefined, displaySummary: undefined })).toBeUndefined();
+    });
+  });
+
+  describe("sections", () => {
+    it("renders the translated title and summary when there is one", () => {
+      const section = {
+        title: "Backend",
+        displayTitle: "Backend (API)",
+        summary: "The API.",
+        displaySummary: "Le API.",
+      };
+      expect(handbookSectionTitle(section)).toBe("Backend (API)");
+      expect(handbookSectionSummary(section)).toBe("Le API.");
+    });
+
+    it("falls back to English when there is none", () => {
+      const section = { title: "Backend", displayTitle: undefined, summary: "The API.", displaySummary: undefined };
+      expect(handbookSectionTitle(section)).toBe("Backend");
+      expect(handbookSectionSummary(section)).toBe("The API.");
+    });
+  });
+
+  /**
+   * An empty string is a translation the ingest wrote, not a missing one, so
+   * `??` is the correct operator and `||` would be wrong: the fallback must
+   * only fire on `undefined`.
+   */
+  it("treats an empty translation as a translation", () => {
+    expect(handbookPageTitle({ title: "Module anatomy", displayTitle: "" })).toBe("");
+  });
+});

package/src/features/handbook/data/handbookDisplay.ts

@@ -0,0 +1,55 @@
+import { HandbookPageInterface } from "./HandbookPageInterface";
+import { HandbookSectionInterface } from "./HandbookSectionInterface";
+
+/**
+ * The handbook is INDEXED in English and SHOWN translated.
+ *
+ * A page's translation lives on the same node as its English original — matched
+ * by `path` at ingest time — and arrives as ordinary attributes beside it.
+ * There is no second id, no locale in any URL and no second resource, so
+ * nothing about ordering, grouping or section membership changes: `path`,
+ * `order` and `section` stay English and are still what every sort reads. Only
+ * the rendered words are resolved here.
+ *
+ * These five functions are the ONE place that resolution happens. A component
+ * reaching for `page.title` directly renders English to an Italian reader, and
+ * a per-component `??` would be five copies of the same rule to keep in step.
+ *
+ * Each parameter is a `Pick` of the interface rather than the whole of it, so a
+ * caller holding a projection — a row from a sparse fieldset, a spec fixture —
+ * passes it without a cast, while a rename on either interface still breaks
+ * this file rather than drifting from it.
+ */
+
+/** The page title to render: the translation when there is one, else English. */
+export function handbookPageTitle(page: Pick<HandbookPageInterface, "title" | "displayTitle">): string {
+  return page.displayTitle ?? page.title;
+}
+
+/** The page's one-line description, translated when the ingest matched one. */
+export function handbookPageSummary(
+  page: Pick<HandbookPageInterface, "summary" | "displaySummary">,
+): string | undefined {
+  return page.displaySummary ?? page.summary;
+}
+
+/**
+ * The markdown body to render. Detail-only, exactly as `content` is:
+ * `displayContent` is the whole file and is absent from every list payload, so
+ * this is never called on a row that came out of a list read.
+ */
+export function handbookPageContent(page: Pick<HandbookPageInterface, "content" | "displayContent">): string {
+  return page.displayContent ?? page.content;
+}
+
+/** The section heading to render, translated when the ingest matched one. */
+export function handbookSectionTitle(section: Pick<HandbookSectionInterface, "title" | "displayTitle">): string {
+  return section.displayTitle ?? section.title;
+}
+
+/** The section blurb to render, translated when the ingest matched one. */
+export function handbookSectionSummary(
+  section: Pick<HandbookSectionInterface, "summary" | "displaySummary">,
+): string | undefined {
+  return section.displaySummary ?? section.summary;
+}

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

@@ -0,0 +1,16 @@
+export * from "./handbookDisplay";
+export * from "./HandbookPage";
+export * from "./HandbookPageFields";
+export * from "./HandbookPageInput";
+export * from "./HandbookPageInterface";
+export * from "./HandbookPageService";
+export * from "./HandbookSection";
+export * from "./HandbookSectionInput";
+export * from "./HandbookSectionInterface";
+export * from "./HandbookSectionService";
+export * from "./HandbookThread";
+export * from "./HandbookThreadInterface";
+export * from "./HandbookThreadMessage";
+export * from "./HandbookThreadMessageInterface";
+export * from "./HandbookThreadMessageService";
+export * from "./HandbookThreadService";

package/src/features/handbook/hooks/__tests__/useHandbookAsk.spec.ts

@@ -0,0 +1,198 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { ApiRequestDataTypeInterface } from "../../../../core/interfaces/ApiRequestDataTypeInterface";
+import { DataClassRegistry } from "../../../../core/registry/DataClassRegistry";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import { HandbookThread } from "../../data/HandbookThread";
+import { HandbookThreadMessage } from "../../data/HandbookThreadMessage";
+import { HandbookThreadMessageService } from "../../data/HandbookThreadMessageService";
+import { HandbookThreadService } from "../../data/HandbookThreadService";
+import { useHandbookAsk } from "../useHandbookAsk";
+
+vi.mock("../../data/HandbookThreadService", () => ({
+  HandbookThreadService: {
+    findMany: vi.fn(),
+    findOne: vi.fn(),
+    create: vi.fn(),
+    rename: vi.fn(),
+    delete: vi.fn(),
+  },
+}));
+
+vi.mock("../../data/HandbookThreadMessageService", () => ({
+  HandbookThreadMessageService: { ask: vi.fn() },
+}));
+
+// The models resolve Modules.HandbookThread / Modules.HandbookThreadMessage
+// lazily through ModuleRegistry, and `_readIncluded` resolves the CONSTRUCTOR
+// through DataClassRegistry. Registering both is the package's spec convention
+// (see HandbookAskContainer.spec.tsx) and is preferred to mocking the core
+// barrel the hook also reads `rehydrate` from.
+const registerIfAbsent = (key: string, module: ApiRequestDataTypeInterface) => {
+  try {
+    ModuleRegistry.get(key as any);
+  } catch {
+    ModuleRegistry.register(key, module);
+  }
+};
+
+beforeAll(() => {
+  registerIfAbsent("HandbookPage", { name: "handbookpages", pageUrl: "/administration/handbook" } as any);
+  const threadModule = { name: "handbookthreads", model: HandbookThread } as any;
+  const messageModule = { name: "handbookthreadmessages", model: HandbookThreadMessage } as any;
+  registerIfAbsent("HandbookThread", threadModule);
+  registerIfAbsent("HandbookThreadMessage", messageModule);
+  DataClassRegistry.registerObjectClass(threadModule, HandbookThread as any);
+  DataClassRegistry.registerObjectClass(messageModule, HandbookThreadMessage as any);
+});
+
+function buildThread(params: {
+  id: string;
+  title: string;
+  messages?: { id: string; role: "user" | "assistant"; content: string; position: number; sources?: string[] }[];
+}): HandbookThread {
+  const messages = params.messages ?? [];
+  return new HandbookThread().rehydrate({
+    jsonApi: {
+      id: params.id,
+      type: "handbookthreads",
+      attributes: { title: params.title },
+      meta: { updatedAt: new Date().toISOString() },
+      relationships: {
+        messages: { data: messages.map((m) => ({ id: m.id, type: "handbookthreadmessages" })) },
+      },
+    },
+    included: messages.map((m) => ({
+      id: m.id,
+      type: "handbookthreadmessages",
+      attributes: { role: m.role, content: m.content, position: m.position, sources: m.sources ?? [] },
+    })),
+  } as any);
+}
+
+const answered = (id: string) =>
+  buildThread({
+    id,
+    title: "Filtri di azienda",
+    messages: [
+      { id: "m1", role: "user", content: "Perché?", position: 0 },
+      { id: "m2", role: "assistant", content: "Inietta il filtro di azienda.", position: 1 },
+    ],
+  });
+
+describe("useHandbookAsk", () => {
+  beforeEach(() => {
+    vi.mocked(HandbookThreadService.findMany).mockReset().mockResolvedValue([]);
+    vi.mocked(HandbookThreadService.findOne).mockReset().mockResolvedValue(answered("t1"));
+    vi.mocked(HandbookThreadService.create)
+      .mockReset()
+      .mockResolvedValue(buildThread({ id: "t1", title: "" }));
+    vi.mocked(HandbookThreadMessageService.ask).mockReset().mockResolvedValue(undefined);
+  });
+
+  it("adds an optimistic user message then replaces the transcript from the read-back", async () => {
+    const { result } = renderHook(() => useHandbookAsk());
+
+    await act(async () => {
+      await result.current.ask("How do migrations run?");
+    });
+
+    await waitFor(() => expect(result.current.messages).toHaveLength(2));
+    expect(HandbookThreadService.findOne).toHaveBeenCalledWith({ id: "t1" });
+    expect(result.current.thread?.id).toBe("t1");
+  });
+
+  it("passes handbookPageId to the create call when one is supplied", async () => {
+    const { result } = renderHook(() => useHandbookAsk({ syncUrl: false }));
+
+    await act(async () => {
+      await result.current.ask("Why?", { handbookPageId: "p2" });
+    });
+
+    expect(HandbookThreadService.create).toHaveBeenCalledWith(expect.objectContaining({ handbookPageId: "p2" }));
+  });
+
+  it("passes handbookPageId to the append call on an open thread", async () => {
+    const { result } = renderHook(() => useHandbookAsk({ syncUrl: false, handbookThreadId: "t1" }));
+    await waitFor(() => expect(result.current.thread?.id).toBe("t1"));
+
+    await act(async () => {
+      await result.current.ask("Why?", { handbookPageId: "p2" });
+    });
+
+    expect(HandbookThreadMessageService.ask).toHaveBeenCalledWith(
+      expect.objectContaining({ threadId: "t1", handbookPageId: "p2" }),
+    );
+    expect(HandbookThreadService.create).not.toHaveBeenCalled();
+  });
+
+  it("keeps the url on the open thread by default", async () => {
+    const replaceState = vi.spyOn(window.history, "replaceState");
+    const { result } = renderHook(() => useHandbookAsk());
+
+    await act(async () => {
+      await result.current.ask("Why?");
+    });
+
+    expect(replaceState).toHaveBeenCalledWith(null, "", "/administration/handbook/chat/t1");
+    replaceState.mockRestore();
+  });
+
+  it("does not touch the URL when syncUrl is false", async () => {
+    const replaceState = vi.spyOn(window.history, "replaceState");
+    const { result } = renderHook(() => useHandbookAsk({ syncUrl: false }));
+
+    await act(async () => {
+      await result.current.ask("Why?");
+    });
+
+    expect(replaceState).not.toHaveBeenCalled();
+    replaceState.mockRestore();
+  });
+
+  it("appends one assistant-side failure message when the API rejects", async () => {
+    vi.mocked(HandbookThreadService.create).mockRejectedValueOnce(new Error("400"));
+    const { result } = renderHook(() => useHandbookAsk());
+
+    await act(async () => {
+      await result.current.ask("Why?");
+    });
+
+    await waitFor(() => expect(result.current.messages).toHaveLength(2));
+    expect(result.current.messages.at(-1)?.role).toBe("assistant");
+    expect(result.current.messages.at(-1)?.content).toBe("handbook.chat.failed");
+    // The asked question stays in the transcript.
+    expect(result.current.messages[0].content).toBe("Why?");
+  });
+
+  it("opens the routed thread on mount without rewriting the url", async () => {
+    const replaceState = vi.spyOn(window.history, "replaceState");
+
+    const { result } = renderHook(() => useHandbookAsk({ handbookThreadId: "t1" }));
+
+    await waitFor(() => expect(result.current.messages).toHaveLength(2));
+    expect(HandbookThreadService.findOne).toHaveBeenCalledWith({ id: "t1" });
+    expect(replaceState).not.toHaveBeenCalled();
+    replaceState.mockRestore();
+  });
+
+  it("loads the thread list and reloads the transcript on select", async () => {
+    vi.mocked(HandbookThreadService.findMany).mockResolvedValue([
+      buildThread({ id: "t1", title: "Filtri di azienda" }),
+    ]);
+    const { result } = renderHook(() => useHandbookAsk());
+
+    await waitFor(() => expect(result.current.threads).toHaveLength(1));
+
+    await act(async () => {
+      await result.current.selectThread("t1");
+    });
+
+    expect(result.current.messages).toHaveLength(2);
+
+    act(() => result.current.startNew());
+    expect(result.current.thread).toBeUndefined();
+    expect(result.current.messages).toHaveLength(0);
+  });
+});