@carlonicora/nextjs-jsonapi 1.77.3 → 1.78.0

package/src/features/assistant-message/AssistantMessageModule.ts

@@ -0,0 +1,28 @@
+import { MessageSquareIcon } from "lucide-react";
+import { createJsonApiInclusion } from "../../core";
+import { ModuleFactory } from "../../permissions";
+import { AssistantMessage } from "./data/AssistantMessage";
+
+export const AssistantMessageModule = (factory: ModuleFactory) =>
+  factory({
+    pageUrl: "/assistant-messages",
+    name: "assistant-messages",
+    model: AssistantMessage,
+    moduleId: "5b2e10e4-3a01-4a59-9f0f-3c4a6c6a8e11",
+    icon: MessageSquareIcon,
+    inclusions: {
+      lists: {
+        fields: [
+          createJsonApiInclusion("assistant-messages", [
+            `role`,
+            `content`,
+            `position`,
+            `suggestedQuestions`,
+            `inputTokens`,
+            `outputTokens`,
+            `references`,
+          ]),
+        ],
+      },
+    },
+  });

package/src/features/assistant-message/components/MessageItem.tsx

@@ -0,0 +1,60 @@
+"use client";
+
+import { useTranslations } from "next-intl";
+import { Sparkles, AlertCircle } from "lucide-react";
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+import type { AssistantMessageInterface } from "../data/AssistantMessageInterface";
+import { ReferenceBadges } from "./parts/ReferenceBadges";
+import { SuggestedFollowUps } from "./parts/SuggestedFollowUps";
+
+interface Props {
+  message: AssistantMessageInterface;
+  isLatestAssistant: boolean;
+  onSelectFollowUp: (q: string) => void;
+  failedMessageIds?: Set<string>;
+  onRetry?: (tempId: string) => void;
+}
+
+export function MessageItem({ message, isLatestAssistant, onSelectFollowUp, failedMessageIds, onRetry }: Props) {
+  const t = useTranslations();
+  const isUser = message.role === "user";
+  const isFailed = isUser && !!failedMessageIds?.has(message.id);
+
+  if (isUser) {
+    return (
+      <div className="flex flex-col items-end gap-1">
+        <div className="bg-primary text-primary-foreground max-w-[72%] rounded-2xl rounded-br-sm px-3.5 py-2 text-sm">
+          {message.content}
+        </div>
+        {isFailed && (
+          <div className="text-destructive flex items-center gap-2 text-xs">
+            <AlertCircle className="h-3.5 w-3.5" />
+            <span>{t("features.assistant.send_failed")}</span>
+            <button type="button" className="underline" onClick={() => onRetry?.(message.id)}>
+              {t("features.assistant.retry")}
+            </button>
+          </div>
+        )}
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex max-w-[78%] flex-col gap-1.5">
+      <div className="text-muted-foreground flex items-center gap-2 pl-1 text-xs">
+        <span className="flex h-4 w-4 items-center justify-center rounded-full bg-gradient-to-br from-blue-400 to-violet-500 text-white">
+          <Sparkles className="h-2.5 w-2.5" />
+        </span>
+        <span>{t("features.assistant.agent_name")}</span>
+      </div>
+      <div className="bg-muted text-foreground rounded-2xl rounded-bl-sm px-3.5 py-2.5 text-sm leading-relaxed">
+        <ReactMarkdown remarkPlugins={[remarkGfm]}>{message.content}</ReactMarkdown>
+      </div>
+      <ReferenceBadges references={message.references} />
+      {isLatestAssistant && (
+        <SuggestedFollowUps questions={message.suggestedQuestions ?? []} onSelect={onSelectFollowUp} />
+      )}
+    </div>
+  );
+}

package/src/features/assistant-message/components/MessageList.tsx

@@ -0,0 +1,38 @@
+"use client";
+
+import { AssistantMessageInterface } from "../data/AssistantMessageInterface";
+import { MessageItem } from "./MessageItem";
+
+interface Props {
+  messages: AssistantMessageInterface[];
+  onSelectFollowUp: (q: string) => void;
+  failedMessageIds?: Set<string>;
+  onRetry?: (tempId: string) => void;
+}
+
+export function MessageList({ messages, onSelectFollowUp, failedMessageIds, onRetry }: Props) {
+  const ordered = [...messages].sort((a, b) => a.position - b.position);
+
+  let lastAssistantIndex = -1;
+  for (let i = ordered.length - 1; i >= 0; i--) {
+    if (ordered[i].role === "assistant") {
+      lastAssistantIndex = i;
+      break;
+    }
+  }
+
+  return (
+    <div className="flex flex-col gap-y-3">
+      {ordered.map((m, i) => (
+        <MessageItem
+          key={m.id}
+          message={m}
+          isLatestAssistant={i === lastAssistantIndex}
+          onSelectFollowUp={onSelectFollowUp}
+          failedMessageIds={failedMessageIds}
+          onRetry={onRetry}
+        />
+      ))}
+    </div>
+  );
+}

package/src/features/assistant-message/components/__tests__/MessageItem.spec.tsx

@@ -0,0 +1,108 @@
+import { describe, it, expect, vi, beforeAll, afterAll } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { AbstractApiData } from "../../../../core/abstracts/AbstractApiData";
+import { DataClassRegistry } from "../../../../core/registry/DataClassRegistry";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import type { ApiRequestDataTypeInterface } from "../../../../core/interfaces/ApiRequestDataTypeInterface";
+import type { ApiDataInterface } from "../../../../core";
+import type { AssistantMessageInterface } from "../../data/AssistantMessageInterface";
+import { MessageItem } from "../MessageItem";
+
+// Test-only account model to exercise ReferenceBadges
+class TestAccount extends AbstractApiData {
+  static identifierFields: string[] = ["name"];
+  rehydrate(data: any): this {
+    super.rehydrate(data);
+    return this;
+  }
+  createJsonApi(): any {
+    return {};
+  }
+}
+const testAccountModule = {
+  name: "test-accounts",
+  pageUrl: "/accounts",
+  model: TestAccount,
+} as unknown as ApiRequestDataTypeInterface;
+
+beforeAll(() => {
+  DataClassRegistry.clear();
+  DataClassRegistry.registerObjectClass(testAccountModule, TestAccount);
+  ModuleRegistry.register("TestAccount" as any, testAccountModule as any);
+});
+afterAll(() => DataClassRegistry.clear());
+
+function makeRehydratedAccount({ id, name }: { id: string; name: string }): ApiDataInterface {
+  const acct = new TestAccount();
+  acct.rehydrate({ jsonApi: { type: "test-accounts", id, attributes: { name } }, included: [] });
+  return acct as unknown as ApiDataInterface;
+}
+
+function buildMessageStub(p: {
+  role: "user" | "assistant";
+  content?: string;
+  references?: ApiDataInterface[];
+  suggestedQuestions?: string[];
+}): AssistantMessageInterface {
+  return {
+    id: Math.random().toString(36).slice(2),
+    type: "assistant-messages",
+    role: p.role,
+    content: p.content ?? "",
+    position: 0,
+    references: p.references ?? [],
+    suggestedQuestions: p.suggestedQuestions ?? [],
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  } as unknown as AssistantMessageInterface;
+}
+
+describe("MessageItem", () => {
+  it("user message is in a right-aligned bubble with plain text", () => {
+    const msg = buildMessageStub({ role: "user", content: "hello" });
+    render(<MessageItem message={msg} isLatestAssistant={false} onSelectFollowUp={vi.fn()} />);
+    expect(screen.getByText("hello")).toBeInTheDocument();
+    // User bubble shouldn't include the assistant agent label
+    expect(screen.queryByText("features.assistant.agent_name")).not.toBeInTheDocument();
+  });
+
+  it("assistant message renders bubble, references, and suggestions toggle when latest", () => {
+    const msg = buildMessageStub({
+      role: "assistant",
+      content: "**bold** reply",
+      references: [makeRehydratedAccount({ id: "acc-1", name: "Acme" })],
+      suggestedQuestions: ["follow-up 1"],
+    });
+    render(<MessageItem message={msg} isLatestAssistant={true} onSelectFollowUp={vi.fn()} />);
+    expect(screen.getByText("features.assistant.agent_name")).toBeInTheDocument();
+    expect(screen.getByRole("link", { name: /acme/i })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: /show_suggestions/ })).toBeInTheDocument();
+  });
+
+  it("assistant message NOT latest: no suggestions toggle", () => {
+    const msg = buildMessageStub({ role: "assistant", content: "prior", suggestedQuestions: ["x"] });
+    render(<MessageItem message={msg} isLatestAssistant={false} onSelectFollowUp={vi.fn()} />);
+    expect(screen.queryByRole("button", { name: /show_suggestions/ })).not.toBeInTheDocument();
+  });
+
+  it("failed user message: renders retry control and calls onRetry with the id", async () => {
+    const msg = buildMessageStub({ role: "user", content: "oops" });
+    (msg as any).id = "tmp-123";
+    const onRetry = vi.fn();
+
+    render(
+      <MessageItem
+        message={msg}
+        isLatestAssistant={false}
+        onSelectFollowUp={vi.fn()}
+        failedMessageIds={new Set(["tmp-123"])}
+        onRetry={onRetry}
+      />,
+    );
+
+    expect(screen.getByText("features.assistant.send_failed")).toBeInTheDocument();
+    const retryBtn = screen.getByRole("button", { name: "features.assistant.retry" });
+    retryBtn.click();
+    expect(onRetry).toHaveBeenCalledWith("tmp-123");
+  });
+});

package/src/features/assistant-message/components/index.ts

@@ -0,0 +1,2 @@
+export * from "./MessageItem";
+export * from "./MessageList";

package/src/features/assistant-message/components/parts/ReferenceBadges.tsx

@@ -0,0 +1,46 @@
+"use client";
+
+import Link from "next/link";
+import { useTranslations } from "next-intl";
+import type { ApiDataInterface } from "../../../../core";
+import { usePageUrlGenerator } from "../../../../hooks";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+
+interface Props {
+  references: ApiDataInterface[];
+}
+
+export function ReferenceBadges({ references }: Props) {
+  const t = useTranslations();
+  const generate = usePageUrlGenerator();
+
+  if (references.length === 0) return null;
+
+  return (
+    <div className="mt-2 flex flex-wrap items-center gap-2">
+      <span className="text-muted-foreground text-xs">{t("features.assistant.references_label")}</span>
+      {references.map((ref) => {
+        // ref.type is the JSON:API type string (same as module.name)
+        let module;
+        try {
+          module = ModuleRegistry.findByName(ref.type);
+        } catch {
+          return null;
+        }
+        const href = generate({ page: module, id: ref.id });
+        return (
+          <Link
+            key={`${ref.type}/${ref.id}`}
+            href={href}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="bg-background border-border text-foreground hover:bg-accent inline-flex items-center gap-1.5 rounded-full border px-2.5 py-0.5 text-xs"
+          >
+            <span className="text-muted-foreground text-[10px]">{module.name}</span>
+            <span className="font-medium">{ref.identifier}</span>
+          </Link>
+        );
+      })}
+    </div>
+  );
+}

package/src/features/assistant-message/components/parts/SuggestedFollowUps.tsx

@@ -0,0 +1,52 @@
+"use client";
+
+import { useState } from "react";
+import { useTranslations } from "next-intl";
+import { ChevronRight, ChevronDown } from "lucide-react";
+
+interface Props {
+  questions: string[];
+  onSelect: (q: string) => void;
+}
+
+export function SuggestedFollowUps({ questions, onSelect }: Props) {
+  const t = useTranslations();
+  const [open, setOpen] = useState(false);
+  if (questions.length === 0) return null;
+
+  return (
+    <div className="mt-2">
+      <button
+        type="button"
+        onClick={() => setOpen((v) => !v)}
+        className="text-primary inline-flex items-center gap-1 text-xs font-medium"
+      >
+        {open ? (
+          <>
+            <ChevronDown className="h-3 w-3" />
+            {t("features.assistant.hide_suggestions")}
+          </>
+        ) : (
+          <>
+            <ChevronRight className="h-3 w-3" />
+            {t("features.assistant.show_suggestions", { count: questions.length })}
+          </>
+        )}
+      </button>
+      {open && (
+        <div className="mt-2 flex flex-col gap-1">
+          {questions.map((q) => (
+            <button
+              key={q}
+              type="button"
+              onClick={() => onSelect(q)}
+              className="border-border bg-muted/30 hover:bg-muted rounded-md border px-3 py-1.5 text-left text-sm"
+            >
+              {q}
+            </button>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/features/assistant-message/components/parts/__tests__/ReferenceBadges.spec.tsx

@@ -0,0 +1,59 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { render, screen } from "@testing-library/react";
+import type { ApiDataInterface } from "../../../../../core";
+import { AbstractApiData } from "../../../../../core/abstracts/AbstractApiData";
+import { DataClassRegistry } from "../../../../../core/registry/DataClassRegistry";
+import { ModuleRegistry } from "../../../../../core/registry/ModuleRegistry";
+import type { ApiRequestDataTypeInterface } from "../../../../../core/interfaces/ApiRequestDataTypeInterface";
+import { ReferenceBadges } from "../ReferenceBadges";
+
+class TestAccount extends AbstractApiData {
+  static identifierFields: string[] = ["name"];
+  rehydrate(data: any): this {
+    super.rehydrate(data);
+    return this;
+  }
+  createJsonApi(): any {
+    return {};
+  }
+}
+
+const testAccountModule = {
+  name: "test-accounts",
+  pageUrl: "/accounts",
+  model: TestAccount,
+} as unknown as ApiRequestDataTypeInterface;
+
+beforeAll(() => {
+  DataClassRegistry.clear();
+  DataClassRegistry.registerObjectClass(testAccountModule, TestAccount);
+  ModuleRegistry.register("TestAccount" as any, testAccountModule as any);
+});
+
+afterAll(() => {
+  DataClassRegistry.clear();
+});
+
+function makeRehydratedAccount({ id, name }: { id: string; name: string }): ApiDataInterface {
+  const acct = new TestAccount();
+  acct.rehydrate({
+    jsonApi: { type: "test-accounts", id, attributes: { name } },
+    included: [],
+  });
+  return acct as unknown as ApiDataInterface;
+}
+
+describe("ReferenceBadges", () => {
+  it("renders a chip per reference with type label + identifier", () => {
+    const references = [makeRehydratedAccount({ id: "acc-1", name: "Acme" })];
+    render(<ReferenceBadges references={references} />);
+    const link = screen.getByRole("link", { name: /acme/i });
+    expect(link).toBeInTheDocument();
+    expect(link.getAttribute("href")).toContain("/accounts/acc-1");
+  });
+
+  it("renders nothing for empty references", () => {
+    const { container } = render(<ReferenceBadges references={[]} />);
+    expect(container.firstChild).toBeNull();
+  });
+});

package/src/features/assistant-message/components/parts/__tests__/SuggestedFollowUps.spec.tsx

@@ -0,0 +1,29 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { SuggestedFollowUps } from "../SuggestedFollowUps";
+
+describe("SuggestedFollowUps", () => {
+  it("is collapsed by default; toggling reveals the buttons", async () => {
+    render(<SuggestedFollowUps questions={["q1", "q2", "q3"]} onSelect={vi.fn()} />);
+    expect(screen.queryByRole("button", { name: "q1" })).not.toBeInTheDocument();
+    const toggle = screen.getByRole("button", { name: /show_suggestions/ });
+    await userEvent.click(toggle);
+    expect(screen.getByRole("button", { name: "q1" })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "q2" })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "q3" })).toBeInTheDocument();
+  });
+
+  it("clicking a question calls onSelect immediately", async () => {
+    const onSelect = vi.fn();
+    render(<SuggestedFollowUps questions={["q1"]} onSelect={onSelect} />);
+    await userEvent.click(screen.getByRole("button", { name: /show_suggestions/ }));
+    await userEvent.click(screen.getByRole("button", { name: "q1" }));
+    expect(onSelect).toHaveBeenCalledWith("q1");
+  });
+
+  it("renders nothing for empty list", () => {
+    const { container } = render(<SuggestedFollowUps questions={[]} onSelect={vi.fn()} />);
+    expect(container.firstChild).toBeNull();
+  });
+});

package/src/features/assistant-message/data/AssistantMessage.ts

@@ -0,0 +1,95 @@
+import { AbstractApiData, ApiDataInterface, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { AssistantMessageInput, AssistantMessageInterface, AssistantMessageRole } from "./AssistantMessageInterface";
+import { resolveReferenceableModules } from "../../assistant/utils/resolveReferenceableModules";
+
+export class AssistantMessage extends AbstractApiData implements AssistantMessageInterface {
+  private _role?: AssistantMessageRole;
+  private _content?: string;
+  private _position?: number;
+  private _suggestedQuestions?: string[];
+  private _inputTokens?: number;
+  private _outputTokens?: number;
+  private _references?: ApiDataInterface[];
+
+  get role(): AssistantMessageRole {
+    return this._role ?? "assistant";
+  }
+
+  get content(): string {
+    return this._content ?? "";
+  }
+
+  get position(): number {
+    return this._position ?? 0;
+  }
+
+  get suggestedQuestions(): string[] {
+    return this._suggestedQuestions ?? [];
+  }
+
+  get inputTokens(): number | undefined {
+    return this._inputTokens;
+  }
+
+  get outputTokens(): number | undefined {
+    return this._outputTokens;
+  }
+
+  get references(): ApiDataInterface[] {
+    return this._references ?? [];
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+    const attrs = data.jsonApi.attributes ?? {};
+    this._role = attrs.role as AssistantMessageRole | undefined;
+    this._content = attrs.content;
+    this._position = typeof attrs.position === "number" ? attrs.position : Number(attrs.position ?? 0);
+    this._suggestedQuestions = Array.isArray(attrs.suggestedQuestions) ? attrs.suggestedQuestions : [];
+    this._inputTokens = attrs.inputTokens;
+    this._outputTokens = attrs.outputTokens;
+    const refs = this._readIncludedPolymorphic<ApiDataInterface>(data, "references", resolveReferenceableModules());
+    this._references = Array.isArray(refs) ? refs : refs ? [refs] : [];
+    return this;
+  }
+
+  createJsonApi(data: AssistantMessageInput) {
+    return {
+      data: {
+        type: Modules.AssistantMessage.name,
+        id: data.id,
+        attributes: {
+          role: data.role,
+          content: data.content,
+          position: data.position,
+        },
+        relationships: {
+          assistant: {
+            data: { type: Modules.Assistant.name, id: data.assistantId },
+          },
+        },
+      },
+      included: [],
+    };
+  }
+
+  static buildOptimistic(params: { content: string; position: number; assistantId?: string }): AssistantMessage {
+    const msg = new AssistantMessage();
+    const jsonApi: Record<string, unknown> = {
+      id: `tmp-${crypto.randomUUID()}`,
+      type: Modules.AssistantMessage.name,
+      attributes: {
+        role: "user",
+        content: params.content,
+        position: params.position,
+      },
+    };
+    if (params.assistantId) {
+      jsonApi.relationships = {
+        assistant: { data: { type: Modules.Assistant.name, id: params.assistantId } },
+      };
+    }
+    msg.rehydrate({ jsonApi: jsonApi as any, included: [] });
+    return msg;
+  }
+}

package/src/features/assistant-message/data/AssistantMessageInterface.ts

@@ -0,0 +1,21 @@
+import { ApiDataInterface } from "../../../core";
+
+export type AssistantMessageRole = "user" | "assistant" | "system";
+
+export type AssistantMessageInput = {
+  id: string;
+  role: AssistantMessageRole;
+  content: string;
+  position: number;
+  assistantId: string;
+};
+
+export interface AssistantMessageInterface extends ApiDataInterface {
+  get role(): AssistantMessageRole;
+  get content(): string;
+  get position(): number;
+  get suggestedQuestions(): string[];
+  get inputTokens(): number | undefined;
+  get outputTokens(): number | undefined;
+  get references(): ApiDataInterface[];
+}

package/src/features/assistant-message/data/AssistantMessageService.ts

@@ -0,0 +1,40 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules, NextRef } from "../../../core";
+import { AssistantMessageInterface } from "./AssistantMessageInterface";
+
+export class AssistantMessageService extends AbstractService {
+  static async findByAssistant(params: { assistantId: string; next?: NextRef }): Promise<AssistantMessageInterface[]> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.Assistant,
+      id: params.assistantId,
+      childEndpoint: Modules.AssistantMessage,
+    });
+    return this.callApi({
+      type: Modules.AssistantMessage,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+      next: params.next,
+    });
+  }
+
+  static async findOne(params: { id: string }): Promise<AssistantMessageInterface> {
+    return this.callApi<AssistantMessageInterface>({
+      type: Modules.AssistantMessage,
+      method: HttpMethod.GET,
+      endpoint: new EndpointCreator({
+        endpoint: Modules.AssistantMessage,
+        id: params.id,
+      }).generate(),
+    });
+  }
+
+  static async delete(params: { id: string }): Promise<void> {
+    await this.callApi({
+      type: Modules.AssistantMessage,
+      method: HttpMethod.DELETE,
+      endpoint: new EndpointCreator({
+        endpoint: Modules.AssistantMessage,
+        id: params.id,
+      }).generate(),
+    });
+  }
+}