@carlonicora/nextjs-jsonapi 3.12.0 → 3.14.0

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

@@ -0,0 +1,60 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules, NextRef, PreviousRef } from "../../../core";
+import { HandbookPageInterface } from "./HandbookPageInterface";
+
+export class HandbookPageService 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<HandbookPageInterface[]> {
+    const endpoint = new EndpointCreator({ endpoint: Modules.HandbookPage });
+
+    if (params.fetchAll) endpoint.addAdditionalParam("fetchAll", "true");
+    if (params.search) endpoint.addAdditionalParam("search", params.search);
+    if (Modules.HandbookPage.inclusions?.lists?.fields)
+      endpoint.limitToFields(Modules.HandbookPage.inclusions.lists.fields);
+    if (Modules.HandbookPage.inclusions?.lists?.types)
+      endpoint.limitToType(Modules.HandbookPage.inclusions.lists.types);
+
+    return this.callApi({
+      type: Modules.HandbookPage,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+      next: params.next,
+    });
+  }
+
+  static async findOne(params: { id: string }): Promise<HandbookPageInterface> {
+    return this.callApi<HandbookPageInterface>({
+      type: Modules.HandbookPage,
+      method: HttpMethod.GET,
+      endpoint: new EndpointCreator({ endpoint: Modules.HandbookPage, id: params.id }).generate(),
+    });
+  }
+
+  /** POST /handbookpages/sync — replies 204; the caller refetches the list. */
+  static async sync(): Promise<void> {
+    await this.callApi({
+      type: Modules.HandbookPage,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({ endpoint: Modules.HandbookPage, id: "sync" }).generate(),
+    });
+  }
+
+  static async delete(params: { id: string }): Promise<void> {
+    await this.callApi({
+      type: Modules.HandbookPage,
+      method: HttpMethod.DELETE,
+      endpoint: new EndpointCreator({ endpoint: Modules.HandbookPage, id: params.id }).generate(),
+    });
+  }
+}

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

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import { HandbookSection } from "./HandbookSection";
+
+describe("HandbookSection", () => {
+  it("rehydrates every attribute", () => {
+    const section = new HandbookSection().rehydrate({
+      jsonApi: {
+        type: "handbooksections",
+        id: "s1",
+        attributes: { key: "03-backend", title: "Backend", summary: "The API.", order: "03-backend" },
+      },
+      included: [],
+    } as any);
+
+    expect(section.key).toBe("03-backend");
+    expect(section.title).toBe("Backend");
+    expect(section.summary).toBe("The API.");
+    expect(section.order).toBe("03-backend");
+  });
+
+  it("defaults missing strings and leaves summary undefined", () => {
+    const section = new HandbookSection().rehydrate({
+      jsonApi: { type: "handbooksections", id: "s1", attributes: {} },
+      included: [],
+    } as any);
+
+    expect(section.key).toBe("");
+    expect(section.title).toBe("");
+    expect(section.summary).toBeUndefined();
+    expect(section.displayTitle).toBeUndefined();
+    expect(section.displaySummary).toBeUndefined();
+  });
+
+  it("rehydrates the translation beside the English original, leaving the key alone", () => {
+    const section = new HandbookSection().rehydrate({
+      jsonApi: {
+        type: "handbooksections",
+        id: "s1",
+        attributes: {
+          key: "03-backend",
+          title: "Backend",
+          summary: "The API.",
+          order: "03-backend",
+          displayTitle: "Backend (API)",
+          displaySummary: "Le API.",
+        },
+      },
+      included: [],
+    } as any);
+
+    expect(section.displayTitle).toBe("Backend (API)");
+    expect(section.displaySummary).toBe("Le API.");
+    // `key` and `order` are what pages are matched and sorted by; they stay
+    // English whatever the translation says.
+    expect(section.key).toBe("03-backend");
+    expect(section.order).toBe("03-backend");
+  });
+});

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

@@ -0,0 +1,73 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { HandbookSectionInput } from "./HandbookSectionInput";
+import { HandbookSectionInterface } from "./HandbookSectionInterface";
+
+export class HandbookSection extends AbstractApiData implements HandbookSectionInterface {
+  private _key?: string;
+  private _title?: string;
+  private _summary?: string;
+  private _order?: string;
+  private _displayTitle?: string;
+  private _displaySummary?: string;
+
+  get key(): string {
+    return this._key ?? "";
+  }
+
+  get title(): string {
+    return this._title ?? "";
+  }
+
+  get summary(): string | undefined {
+    return this._summary;
+  }
+
+  get order(): string {
+    return this._order ?? "";
+  }
+
+  get displayTitle(): string | undefined {
+    return this._displayTitle;
+  }
+
+  get displaySummary(): string | undefined {
+    return this._displaySummary;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    this._key = data.jsonApi.attributes.key;
+    this._title = data.jsonApi.attributes.title;
+    this._summary = data.jsonApi.attributes.summary;
+    this._order = data.jsonApi.attributes.order;
+    this._displayTitle = data.jsonApi.attributes.displayTitle;
+    this._displaySummary = data.jsonApi.attributes.displaySummary;
+
+    return this;
+  }
+
+  /**
+   * Nothing calls this: sections are read-only over HTTP and written only by
+   * the ingest. It exists because every model implements `createJsonApi()`, and
+   * a model that throws on serialisation is a trap for the next writer.
+   */
+  createJsonApi(data: HandbookSectionInput) {
+    const response: any = {
+      data: {
+        type: Modules.HandbookSection.name,
+        id: data.id,
+        attributes: {},
+        relationships: {},
+      },
+      included: [],
+    };
+
+    if (data.key !== undefined) response.data.attributes.key = data.key;
+    if (data.title !== undefined) response.data.attributes.title = data.title;
+    if (data.summary !== undefined) response.data.attributes.summary = data.summary;
+    if (data.order !== undefined) response.data.attributes.order = data.order;
+
+    return response;
+  }
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Handbook sections are written only by the backend ingest, which replaces
+ * every one of them on each sync. No client ever posts one; this type exists so
+ * the model can satisfy AbstractApiData's `createJsonApi()` contract.
+ */
+export type HandbookSectionInput = {
+  id: string;
+  key: string;
+  title: string;
+  summary?: string;
+  order: string;
+};

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

@@ -0,0 +1,26 @@
+import { ApiDataInterface } from "../../../core";
+
+/**
+ * One top-level directory of the configured documentation tree.
+ *
+ * A page names its section by `key`, not by edge, so this interface carries no
+ * relationships: the contents page reads sections and pages in two calls and
+ * groups them client side.
+ */
+export interface HandbookSectionInterface extends ApiDataInterface {
+  /** The directory name, e.g. `03-backend`. The natural key of the ingest. */
+  get key(): string;
+  /** The prettified `key`, or the README heading when the index names one. */
+  get title(): string;
+  /** The README's blurb for the section. Absent when the tree has no index. */
+  get summary(): string | undefined;
+  /** The `key`; sorting on it reproduces the directories' numeric order. */
+  get order(): string;
+  /**
+   * The translated rendering of `title`, when the index carries one. Every
+   * reader-facing surface renders `displayTitle ?? title`.
+   */
+  get displayTitle(): string | undefined;
+  /** The translated `summary`. Absent when the section has no translation. */
+  get displaySummary(): string | undefined;
+}

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

@@ -0,0 +1,26 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules } from "../../../core";
+import { HandbookSectionInterface } from "./HandbookSectionInterface";
+
+export class HandbookSectionService extends AbstractService {
+  /**
+   * Every section in one read, always.
+   *
+   * There are as many sections as an application has documentation directories
+   * — ten or so — so this takes no `fetchAll` argument and no cursor: unlike
+   * the page list, nothing here is ever a second page, and a caller that could
+   * ask for one page of sections would only be able to get it wrong.
+   */
+  static async findMany(): Promise<HandbookSectionInterface[]> {
+    const endpoint = new EndpointCreator({ endpoint: Modules.HandbookSection });
+
+    endpoint.addAdditionalParam("fetchAll", "true");
+    if (Modules.HandbookSection.inclusions?.lists?.fields)
+      endpoint.limitToFields(Modules.HandbookSection.inclusions.lists.fields);
+
+    return this.callApi({
+      type: Modules.HandbookSection,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+    });
+  }
+}

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

@@ -0,0 +1,114 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { HandbookThreadInput, HandbookThreadInterface } from "./HandbookThreadInterface";
+import { HandbookThreadMessageInterface } from "./HandbookThreadMessageInterface";
+
+export class HandbookThread extends AbstractApiData implements HandbookThreadInterface {
+  private _title?: string;
+  private _messageCount?: number;
+  private _messages?: HandbookThreadMessageInterface[];
+
+  get title(): string {
+    return this._title ?? "";
+  }
+
+  get messageCount(): number {
+    return this._messageCount ?? 0;
+  }
+
+  /**
+   * The handbook runs one agent and has no engine choice, so nothing routes on
+   * this. It exists because `AssistantInterface` declares it, which is what
+   * lets the shared chat chrome take a handbook thread unchanged.
+   */
+  get engine(): string | undefined {
+    return undefined;
+  }
+
+  /** A handbook thread is never bound to a product resource. */
+  get boundContentType(): string | undefined {
+    return undefined;
+  }
+
+  get boundContentId(): string | undefined {
+    return undefined;
+  }
+
+  get messages(): HandbookThreadMessageInterface[] {
+    return this._messages ?? [];
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attributes = data.jsonApi.attributes ?? {};
+    this._title = attributes.title;
+
+    const fromMeta = data.jsonApi.meta?.messageCount;
+    this._messageCount =
+      typeof fromMeta === "number"
+        ? fromMeta
+        : typeof attributes.messageCount === "number"
+          ? attributes.messageCount
+          : 0;
+
+    const messages = this._readIncluded<HandbookThreadMessageInterface>(
+      data,
+      "messages",
+      Modules.HandbookThreadMessage,
+    );
+    this._messages = Array.isArray(messages) ? messages : messages ? [messages] : [];
+
+    // `groupThreadsByBucket` buckets the sidebar on `updatedAt` as a Date, and
+    // `AbstractApiData` only reads it from `meta`. A thread that carries the
+    // timestamp as an attribute instead would otherwise fall back to "now" and
+    // land every thread in "Today".
+    if (this._updatedAt === undefined && attributes.updatedAt !== undefined)
+      this._updatedAt = new Date(attributes.updatedAt);
+    if (this._createdAt === undefined && attributes.createdAt !== undefined)
+      this._createdAt = new Date(attributes.createdAt);
+
+    return this;
+  }
+
+  /**
+   * The envelope `POST /handbookthreads` accepts: the opening question. The
+   * server derives the title from it, so no title is sent and no client id —
+   * the thread's identity is the server's to mint.
+   *
+   * `handbookPageId` rides the same way `question` does, through this method
+   * and never through `overridesJsonApiCreation`. It is written only when the
+   * caller supplied it: the DTO takes it as optional, and sending an explicit
+   * `null` would fail validation rather than mean "the whole manual".
+   */
+  createJsonApi(data: HandbookThreadInput) {
+    return {
+      data: {
+        type: Modules.HandbookThread.name,
+        attributes: {
+          question: data.question,
+          ...(data.handbookPageId !== undefined ? { handbookPageId: data.handbookPageId } : {}),
+        },
+      },
+      included: [],
+    };
+  }
+
+  /**
+   * The envelope `PATCH /handbookthreads/:id` accepts. A dedicated method
+   * rather than a branch inside `createJsonApi`: the rename sends the title and
+   * nothing else, while a create sends the question and nothing else, and the
+   * service must never hand-build either.
+   */
+  createRenameJsonApi(params: { id: string; title: string }) {
+    return {
+      data: {
+        type: Modules.HandbookThread.name,
+        id: params.id,
+        attributes: {
+          title: params.title,
+        },
+      },
+      included: [],
+    };
+  }
+}

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

@@ -0,0 +1,31 @@
+import { AssistantInterface } from "../../assistant/data/AssistantInterface";
+import { HandbookThreadMessageInterface } from "./HandbookThreadMessageInterface";
+
+/**
+ * A persisted handbook conversation.
+ *
+ * It extends `AssistantInterface` so the shared chat chrome —
+ * `AssistantSidebar`, `AssistantThreadHeader`, `groupThreadsByBucket` — accepts
+ * it verbatim. It is NOT an Assistant: an Assistant is company scoped and a
+ * platform administrator has no company, so the handbook owns its own threads
+ * and answers `engine` / `boundContentType` / `boundContentId` with `undefined`.
+ */
+export interface HandbookThreadInterface extends AssistantInterface {
+  /** Side-loaded by `GET /handbookthreads/:id`; empty on the list endpoint. */
+  get messages(): HandbookThreadMessageInterface[];
+}
+
+/**
+ * The payload that opens a thread: the first question. The server derives the
+ * title from it, so nothing else is sent.
+ */
+export type HandbookThreadInput = {
+  id: string;
+  question: string;
+  /**
+   * Scopes retrieval to one handbook page. Set only by the reader's ask sheet,
+   * when the reader turns the "this page only" chip on; absent everywhere else,
+   * and the agent then searches the whole manual.
+   */
+  handbookPageId?: string;
+};

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

@@ -0,0 +1,144 @@
+import { v4 as uuidv4 } from "uuid";
+import { AbstractApiData, ApiDataInterface, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import type {
+  AssistantMessageRole,
+  AssistantMessageType,
+} from "../../assistant-message/data/AssistantMessageInterface";
+import { ChunkInterface, ChunkRelationshipMeta } from "../../chunk/data/ChunkInterface";
+import { HandbookThreadMessageInput, HandbookThreadMessageInterface } from "./HandbookThreadMessageInterface";
+
+/**
+ * One persisted handbook turn.
+ *
+ * The getters below are the structural contract `AssistantMessageInterface`
+ * asks for, which is what lets `AssistantThread` render handbook messages with
+ * no adapter. The handbook has no token accounting, no entity references, no
+ * chunk citations and no approval actions, so those answer `undefined` / `[]`
+ * rather than being faked.
+ */
+export class HandbookThreadMessage extends AbstractApiData implements HandbookThreadMessageInterface {
+  private _role?: AssistantMessageRole;
+  private _content?: string;
+  private _position?: number;
+  private _sources?: string[];
+  private _isOptimistic = false;
+
+  get role(): AssistantMessageRole {
+    return this._role ?? "assistant";
+  }
+
+  get content(): string {
+    return this._content ?? "";
+  }
+
+  get position(): number {
+    return this._position ?? 0;
+  }
+
+  get sources(): string[] {
+    return this._sources ?? [];
+  }
+
+  /** The handbook agent returns no follow-ups. */
+  get suggestedQuestions(): string[] {
+    return [];
+  }
+
+  /** Token accounting is not billed against a handbook thread. */
+  get inputTokens(): number | undefined {
+    return undefined;
+  }
+
+  get outputTokens(): number | undefined {
+    return undefined;
+  }
+
+  /** The handbook answers from pages, never from product entities. */
+  get references(): ApiDataInterface[] {
+    return [];
+  }
+
+  /** Cited pages travel in `sources`, not as Chunk resources. */
+  get citations(): (ChunkInterface & ChunkRelationshipMeta)[] {
+    return [];
+  }
+
+  /** Set only by `buildLocal`; a rehydrated message is always real. */
+  get isOptimistic(): boolean {
+    return this._isOptimistic;
+  }
+
+  /** There is no operator engine behind the handbook, so never an approval request. */
+  get messageType(): AssistantMessageType {
+    return "text";
+  }
+
+  get actionId(): string | undefined {
+    return undefined;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attributes = data.jsonApi.attributes ?? {};
+    this._role = attributes.role as AssistantMessageRole | undefined;
+    this._content = attributes.content;
+    this._position = typeof attributes.position === "number" ? attributes.position : Number(attributes.position ?? 0);
+    this._sources = Array.isArray(attributes.sources) ? attributes.sources : [];
+
+    return this;
+  }
+
+  /**
+   * The envelope `POST /handbookthreads/:id/handbookthreadmessages` accepts:
+   * only the question. Role and position are derived server-side from the
+   * thread, and there is no client-chosen id for the pair of messages the turn
+   * creates.
+   *
+   * `handbookPageId` rides the same way `question` does, through this method
+   * and never through `overridesJsonApiCreation`. It is written only when the
+   * caller supplied it: the DTO takes it as optional, and sending an explicit
+   * `null` would fail validation rather than mean "the whole manual".
+   */
+  createJsonApi(data: HandbookThreadMessageInput) {
+    return {
+      data: {
+        type: Modules.HandbookThreadMessage.name,
+        attributes: {
+          question: data.question,
+          ...(data.handbookPageId !== undefined ? { handbookPageId: data.handbookPageId } : {}),
+        },
+      },
+      included: [],
+    };
+  }
+
+  /**
+   * A message that exists only on the client: the optimistic user turn while
+   * the agent runs, and the failure notice when it does not answer. Mirrors
+   * `AssistantMessage.buildLocal`, which the stateless handbook surface used
+   * before threads existed.
+   */
+  static buildLocal(params: {
+    role: AssistantMessageRole;
+    content: string;
+    position: number;
+    isOptimistic?: boolean;
+  }): HandbookThreadMessage {
+    const message = new HandbookThreadMessage();
+    message.rehydrate({
+      jsonApi: {
+        id: uuidv4(),
+        type: Modules.HandbookThreadMessage.name,
+        attributes: {
+          role: params.role,
+          content: params.content,
+          position: params.position,
+        },
+      } as any,
+      included: [],
+    });
+    message._isOptimistic = params.isOptimistic ?? false;
+    return message;
+  }
+}

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

@@ -0,0 +1,35 @@
+import { AssistantMessageInterface } from "../../assistant-message/data/AssistantMessageInterface";
+
+/**
+ * One turn of a persisted handbook conversation.
+ *
+ * It extends `AssistantMessageInterface` rather than restating it: the shared
+ * chat components (`AssistantThread` → `MessageList` → `MessageItem`) are typed
+ * against that interface and take their data as plain props, so a handbook
+ * message that satisfies the same structural contract renders through them with
+ * no adapter. Everything the handbook has no concept of — token counts,
+ * references, citations, approval actions — is answered with the empty value.
+ *
+ * `sources` is the handbook's own addition: repo-relative page paths, in the
+ * order retrieval returned them.
+ */
+export interface HandbookThreadMessageInterface extends AssistantMessageInterface {
+  get sources(): string[];
+}
+
+/**
+ * The payload of one question appended to an existing thread. `id` is the
+ * client-generated identity every model input in this framework carries; the
+ * append endpoint derives role and position server-side, so the envelope the
+ * model builds sends only `question`.
+ */
+export type HandbookThreadMessageInput = {
+  id: string;
+  question: string;
+  /**
+   * Scopes retrieval to one handbook page. Set only by the reader's ask sheet,
+   * when the reader turns the "this page only" chip on; absent everywhere else,
+   * and the agent then searches the whole manual.
+   */
+  handbookPageId?: string;
+};

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

@@ -0,0 +1,30 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules } from "../../../core";
+import { HandbookThreadMessageInput } from "./HandbookThreadMessageInterface";
+
+export class HandbookThreadMessageService extends AbstractService {
+  /**
+   * Appends one question to an existing thread and runs the agent turn.
+   *
+   * It returns nothing on purpose: the caller reads the turn back with
+   * `HandbookThreadService.findOne`, which is the one endpoint the contract
+   * guarantees side-loads the full message list. That keeps a single code path
+   * for "load the thread after a mutation" — the same one the sidebar's select
+   * uses — instead of two ways of arriving at the transcript.
+   *
+   * 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.
+   */
+  static async ask(params: HandbookThreadMessageInput & { threadId: string }): Promise<void> {
+    await this.callApi({
+      type: Modules.HandbookThreadMessage,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({
+        endpoint: Modules.HandbookThread,
+        id: params.threadId,
+        childEndpoint: Modules.HandbookThreadMessage,
+      }).generate(),
+      input: { id: params.id, question: params.question, handbookPageId: params.handbookPageId },
+      suppressGlobalError: true,
+    });
+  }
+}