@carlonicora/nextjs-jsonapi 1.79.0 → 1.81.0

package/src/features/assistant-message/components/parts/tabs/CitationsTab.tsx

@@ -0,0 +1,105 @@
+"use client";
+
+import { Fragment, useState } from "react";
+import { useTranslations } from "next-intl";
+import { ChevronDown, HelpCircle } from "lucide-react";
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+import type { ApiDataInterface } from "../../../../../core";
+import type { ChunkInterface, ChunkRelationshipMeta } from "../../../../chunk/data/ChunkInterface";
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "../../../../../shadcnui/ui/table";
+import { Tooltip, TooltipContent, TooltipTrigger } from "../../../../../shadcnui/ui/tooltip";
+import { cn } from "@/lib/utils";
+import { RelevanceMeter } from "../RelevanceMeter";
+
+interface Props {
+  citations: (ChunkInterface & ChunkRelationshipMeta)[];
+  /**
+   * Resolved source entities keyed by `chunk.nodeId`. When provided, the row
+   * label is the entity's `name`; otherwise it falls back to the nodeType + a
+   * short id.
+   */
+  sources?: Map<string, ApiDataInterface>;
+}
+
+export function CitationsTab({ citations, sources }: Props) {
+  const t = useTranslations();
+  const [expanded, setExpanded] = useState<Set<string>>(new Set());
+  if (citations.length === 0) return null;
+
+  const sorted = [...citations].sort((a, b) => (b.relevance ?? 0) - (a.relevance ?? 0));
+
+  const toggle = (id: string) => {
+    setExpanded((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+      return next;
+    });
+  };
+
+  return (
+    <Table className="table-fixed">
+      <TableHeader>
+        <TableRow>
+          <TableHead>{t("features.assistant.message.sources.source")}</TableHead>
+          <TableHead className="w-28 text-center">{t("features.assistant.message.sources.relevance")}</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {sorted.map((chunk) => {
+          const isOpen = expanded.has(chunk.id);
+          const resolved = chunk.nodeId ? sources?.get(chunk.nodeId) : undefined;
+          const fallbackName = chunk.nodeId
+            ? `${chunk.nodeType ?? t("features.assistant.message.sources.source")} ${chunk.nodeId.slice(0, 8)}`
+            : (chunk.nodeType ?? t("features.assistant.message.sources.source"));
+          const sourceName = (resolved as any)?.name ?? fallbackName;
+          return (
+            <Fragment key={chunk.id}>
+              <TableRow>
+                <TableCell>
+                  <div
+                    role="button"
+                    tabIndex={0}
+                    onClick={() => toggle(chunk.id)}
+                    onKeyDown={(e) => {
+                      if (e.key === "Enter" || e.key === " ") {
+                        e.preventDefault();
+                        toggle(chunk.id);
+                      }
+                    }}
+                    aria-expanded={isOpen}
+                    className="flex w-full cursor-pointer items-center justify-start gap-x-2"
+                  >
+                    <ChevronDown className={cn("h-4 w-4 transition-transform", !isOpen && "-rotate-90")} />
+                    <span className="font-semibold">{sourceName}</span>
+                    {chunk.reason && (
+                      <Tooltip>
+                        <TooltipTrigger className="text-muted-foreground inline-flex">
+                          <HelpCircle className="h-3.5 w-3.5" />
+                        </TooltipTrigger>
+                        <TooltipContent className="max-w-64 text-xs">{chunk.reason}</TooltipContent>
+                      </Tooltip>
+                    )}
+                  </div>
+                </TableCell>
+                <TableCell className="text-center">
+                  <RelevanceMeter value={chunk.relevance ?? 0} />
+                </TableCell>
+              </TableRow>
+              {isOpen && (
+                <TableRow>
+                  <TableCell colSpan={2} className="border-t-0 p-4">
+                    <div className="bg-card w-full max-w-full overflow-x-auto rounded border p-4 text-sm break-words">
+                      <ReactMarkdown remarkPlugins={[remarkGfm]}>{chunk.content}</ReactMarkdown>
+                    </div>
+                  </TableCell>
+                </TableRow>
+              )}
+            </Fragment>
+          );
+        })}
+      </TableBody>
+    </Table>
+  );
+}

package/src/features/assistant-message/components/parts/tabs/ContentsTab.tsx

@@ -0,0 +1,88 @@
+"use client";
+
+import Link from "next/link";
+import { useTranslations } from "next-intl";
+import type { ApiDataInterface } from "../../../../../core";
+import { ModuleRegistry } from "../../../../../core/registry/ModuleRegistry";
+import { usePageUrlGenerator } from "../../../../../hooks";
+import type { ChunkInterface, ChunkRelationshipMeta } from "../../../../chunk/data/ChunkInterface";
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "../../../../../shadcnui/ui/table";
+
+interface Props {
+  citations: (ChunkInterface & ChunkRelationshipMeta)[];
+  /** Resolved source entities keyed by `chunk.nodeId`. */
+  sources?: Map<string, ApiDataInterface>;
+}
+
+interface ContentRow {
+  source: ApiDataInterface;
+  citationCount: number;
+  maxRelevance: number;
+}
+
+export function ContentsTab({ citations, sources }: Props) {
+  const t = useTranslations();
+  const generate = usePageUrlGenerator();
+
+  // Group citations by nodeId, then materialise rows from the resolved sources
+  // map. Chunks without a resolved source entity are skipped.
+  const map = new Map<string, ContentRow>();
+  for (const c of citations) {
+    const id = c.nodeId;
+    if (!id) continue;
+    const source = sources?.get(id);
+    if (!source) continue;
+    const existing = map.get(id);
+    if (existing) {
+      existing.citationCount++;
+      existing.maxRelevance = Math.max(existing.maxRelevance, c.relevance ?? 0);
+    } else {
+      map.set(id, { source, citationCount: 1, maxRelevance: c.relevance ?? 0 });
+    }
+  }
+
+  const rows = Array.from(map.values()).sort(
+    (a, b) =>
+      b.maxRelevance - a.maxRelevance || ((a.source as any).name ?? "").localeCompare((b.source as any).name ?? ""),
+  );
+
+  if (rows.length === 0) return null;
+
+  return (
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHead>{t("features.assistant.message.sources.source")}</TableHead>
+          <TableHead className="w-32">{t("features.assistant.message.sources.type")}</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {rows.map(({ source, citationCount }) => {
+          let module;
+          try {
+            module = ModuleRegistry.findByName(source.type);
+          } catch {
+            return null;
+          }
+          const href = generate({ page: module, id: source.id });
+          const name = (source as any).name ?? source.identifier;
+          return (
+            <TableRow key={`${source.type}/${source.id}`}>
+              <TableCell>
+                <Link href={href} target="_blank" rel="noopener noreferrer" className="hover:underline">
+                  <span className="font-medium">{name}</span>{" "}
+                  <span className="text-muted-foreground text-xs">
+                    {t("features.assistant.message.sources.citations_count", {
+                      count: citationCount,
+                    })}
+                  </span>
+                </Link>
+              </TableCell>
+              <TableCell className="text-muted-foreground text-xs">{module.name}</TableCell>
+            </TableRow>
+          );
+        })}
+      </TableBody>
+    </Table>
+  );
+}

package/src/features/assistant-message/components/parts/tabs/ReferencesTab.tsx

@@ -0,0 +1,51 @@
+"use client";
+
+import Link from "next/link";
+import { useTranslations } from "next-intl";
+import type { ApiDataInterface } from "../../../../../core";
+import { ModuleRegistry } from "../../../../../core/registry/ModuleRegistry";
+import { usePageUrlGenerator } from "../../../../../hooks";
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "../../../../../shadcnui/ui/table";
+
+interface Props {
+  references: ApiDataInterface[];
+}
+
+export function ReferencesTab({ references }: Props) {
+  const t = useTranslations();
+  const generate = usePageUrlGenerator();
+
+  if (references.length === 0) return null;
+
+  return (
+    <Table>
+      <TableHeader>
+        <TableRow>
+          <TableHead>{t("features.assistant.message.sources.source")}</TableHead>
+          <TableHead className="w-32">{t("features.assistant.message.sources.type")}</TableHead>
+        </TableRow>
+      </TableHeader>
+      <TableBody>
+        {references.map((ref) => {
+          let module;
+          try {
+            module = ModuleRegistry.findByName(ref.type);
+          } catch {
+            return null;
+          }
+          const href = generate({ page: module, id: ref.id });
+          return (
+            <TableRow key={`${ref.type}/${ref.id}`}>
+              <TableCell>
+                <Link href={href} target="_blank" rel="noopener noreferrer" className="font-medium hover:underline">
+                  {ref.identifier}
+                </Link>
+              </TableCell>
+              <TableCell className="text-muted-foreground text-xs">{module.name}</TableCell>
+            </TableRow>
+          );
+        })}
+      </TableBody>
+    </Table>
+  );
+}

package/src/features/assistant-message/components/parts/tabs/SuggestedQuestionsTab.tsx

@@ -0,0 +1,24 @@
+"use client";
+
+interface Props {
+  questions: string[];
+  onSelect: (question: string) => void;
+}
+
+export function SuggestedQuestionsTab({ questions, onSelect }: Props) {
+  if (questions.length === 0) return null;
+  return (
+    <div className="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>
+  );
+}

package/src/features/assistant-message/components/parts/tabs/UsersTab.tsx

@@ -0,0 +1,142 @@
+"use client";
+
+import Link from "next/link";
+import { useTranslations } from "next-intl";
+import type { ApiDataInterface } from "../../../../../core";
+import { ModuleRegistry } from "../../../../../core/registry/ModuleRegistry";
+import { usePageUrlGenerator } from "../../../../../hooks";
+import type { ChunkInterface, ChunkRelationshipMeta } from "../../../../chunk/data/ChunkInterface";
+import { Avatar, AvatarFallback, AvatarImage } from "../../../../../shadcnui/ui/avatar";
+import { Table, TableBody, TableCell, TableRow } from "../../../../../shadcnui/ui/table";
+
+interface Props {
+  /** Pre-deduplicated list of authors derived from the resolved sources. */
+  users: ApiDataInterface[];
+  /**
+   * Optional citations + sources used to compute per-user content/citation
+   * counts. When omitted, only the user list is shown.
+   */
+  citations?: (ChunkInterface & ChunkRelationshipMeta)[];
+  sources?: Map<string, ApiDataInterface>;
+}
+
+interface UserRow {
+  user: ApiDataInterface;
+  contentCount: number;
+  citationCount: number;
+}
+
+function getInitials(name: string): string {
+  return name
+    .split(/\s+/)
+    .map((p) => p.charAt(0))
+    .filter(Boolean)
+    .slice(0, 2)
+    .join("")
+    .toUpperCase();
+}
+
+function readAuthor(source: ApiDataInterface): ApiDataInterface | undefined {
+  // The Content base class throws on missing author. Catch defensively so a
+  // partially-hydrated source never breaks the UI.
+  try {
+    const a = (source as any).author;
+    return a && a.id ? a : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function UsersTab({ users, citations, sources }: Props) {
+  const t = useTranslations();
+  const generate = usePageUrlGenerator();
+
+  // Build per-user counts. If we have citations + sources, compute real counts.
+  // Otherwise fall back to one row per user with no counts.
+  const userMap = new Map<string, UserRow>();
+  for (const u of users) {
+    if (!u?.id) continue;
+    userMap.set(u.id, { user: u, contentCount: 0, citationCount: 0 });
+  }
+
+  if (citations && sources) {
+    const sourceUserPairs = new Set<string>();
+    for (const c of citations) {
+      const id = c.nodeId;
+      if (!id) continue;
+      const source = sources.get(id);
+      if (!source) continue;
+      const author = readAuthor(source);
+      if (!author) continue;
+
+      let row = userMap.get(author.id);
+      if (!row) {
+        row = { user: author, contentCount: 0, citationCount: 0 };
+        userMap.set(author.id, row);
+      }
+      const sourceUserKey = `${source.id}:${author.id}`;
+      if (!sourceUserPairs.has(sourceUserKey)) {
+        sourceUserPairs.add(sourceUserKey);
+        row.contentCount++;
+      }
+      row.citationCount++;
+    }
+  }
+
+  const rows = Array.from(userMap.values()).sort(
+    (a, b) =>
+      b.citationCount - a.citationCount || ((a.user as any).name ?? "").localeCompare((b.user as any).name ?? ""),
+  );
+
+  if (rows.length === 0) return null;
+
+  return (
+    <Table>
+      <TableBody>
+        {rows.map(({ user, contentCount, citationCount }) => {
+          let module;
+          try {
+            module = ModuleRegistry.findByName(user.type);
+          } catch {
+            return null;
+          }
+          const href = generate({ page: module, id: user.id });
+          const name = (user as any).name ?? (user as any).fullName ?? user.identifier ?? "User";
+          const avatarUrl = (user as any).avatar as string | undefined;
+          const showCounts = citationCount > 0 || contentCount > 0;
+          return (
+            <TableRow key={user.id}>
+              <TableCell>
+                <Link
+                  href={href}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="flex items-center gap-3 hover:underline"
+                >
+                  <Avatar className="h-7 w-7">
+                    <AvatarImage src={avatarUrl} aria-label={name} />
+                    <AvatarFallback aria-label={name}>{getInitials(name)}</AvatarFallback>
+                  </Avatar>
+                  <span className="flex flex-col">
+                    <span className="font-medium">{name}</span>
+                    {showCounts && (
+                      <span className="text-muted-foreground text-xs">
+                        {t("features.assistant.message.sources.contents_count", {
+                          count: contentCount,
+                        })}
+                        {" · "}
+                        {t("features.assistant.message.sources.citations_count", {
+                          count: citationCount,
+                        })}
+                      </span>
+                    )}
+                  </span>
+                </Link>
+              </TableCell>
+            </TableRow>
+          );
+        })}
+      </TableBody>
+    </Table>
+  );
+}

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

@@ -1,6 +1,7 @@
 import { AbstractApiData, ApiDataInterface, JsonApiHydratedDataInterface, Modules } from "../../../core";
 import { AssistantMessageInput, AssistantMessageInterface, AssistantMessageRole } from "./AssistantMessageInterface";
 import { resolveReferenceableModules } from "../../assistant/utils/resolveReferenceableModules";
+import { ChunkInterface, ChunkRelationshipMeta } from "../../chunk/data/ChunkInterface";
 
 export class AssistantMessage extends AbstractApiData implements AssistantMessageInterface {
   private _role?: AssistantMessageRole;
@@ -10,6 +11,7 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
   private _inputTokens?: number;
   private _outputTokens?: number;
   private _references?: ApiDataInterface[];
+  private _citations?: (ChunkInterface & ChunkRelationshipMeta)[];
 
   get role(): AssistantMessageRole {
     return this._role ?? "assistant";
@@ -39,6 +41,10 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
     return this._references ?? [];
   }
 
+  get citations(): (ChunkInterface & ChunkRelationshipMeta)[] {
+    return this._citations ?? [];
+  }
+
   rehydrate(data: JsonApiHydratedDataInterface): this {
     super.rehydrate(data);
     const attrs = data.jsonApi.attributes ?? {};
@@ -50,6 +56,20 @@ export class AssistantMessage extends AbstractApiData implements AssistantMessag
     this._outputTokens = attrs.outputTokens;
     const refs = this._readIncludedPolymorphic<ApiDataInterface>(data, "references", resolveReferenceableModules());
     this._references = Array.isArray(refs) ? refs : refs ? [refs] : [];
+    if (data.jsonApi.relationships?.citations?.data) {
+      const citations = this._readIncludedWithMeta<ChunkInterface, ChunkRelationshipMeta>(
+        data,
+        "citations",
+        Modules.Chunk,
+      );
+      this._citations = Array.isArray(citations)
+        ? (citations as (ChunkInterface & ChunkRelationshipMeta)[])
+        : citations
+          ? [citations as ChunkInterface & ChunkRelationshipMeta]
+          : [];
+    } else {
+      this._citations = [];
+    }
     return this;
   }
 

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

@@ -1,4 +1,5 @@
 import { ApiDataInterface } from "../../../core";
+import { ChunkInterface, ChunkRelationshipMeta } from "../../chunk/data/ChunkInterface";
 
 export type AssistantMessageRole = "user" | "assistant" | "system";
 
@@ -18,4 +19,5 @@ export interface AssistantMessageInterface extends ApiDataInterface {
   get inputTokens(): number | undefined;
   get outputTokens(): number | undefined;
   get references(): ApiDataInterface[];
+  get citations(): (ChunkInterface & ChunkRelationshipMeta)[];
 }

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

@@ -8,6 +8,10 @@ export class AssistantMessageService extends AbstractService {
       id: params.assistantId,
       childEndpoint: Modules.AssistantMessage,
     });
+    if (Modules.AssistantMessage.inclusions?.lists?.fields)
+      endpoint.limitToFields(Modules.AssistantMessage.inclusions.lists.fields);
+    if (Modules.AssistantMessage.inclusions?.lists?.types)
+      endpoint.limitToType(Modules.AssistantMessage.inclusions.lists.types);
     return this.callApi({
       type: Modules.AssistantMessage,
       method: HttpMethod.GET,
@@ -17,13 +21,18 @@ export class AssistantMessageService extends AbstractService {
   }
 
   static async findOne(params: { id: string }): Promise<AssistantMessageInterface> {
+    const endpoint = new EndpointCreator({
+      endpoint: Modules.AssistantMessage,
+      id: params.id,
+    });
+    if (Modules.AssistantMessage.inclusions?.lists?.fields)
+      endpoint.limitToFields(Modules.AssistantMessage.inclusions.lists.fields);
+    if (Modules.AssistantMessage.inclusions?.lists?.types)
+      endpoint.limitToType(Modules.AssistantMessage.inclusions.lists.types);
     return this.callApi<AssistantMessageInterface>({
       type: Modules.AssistantMessage,
       method: HttpMethod.GET,
-      endpoint: new EndpointCreator({
-        endpoint: Modules.AssistantMessage,
-        id: params.id,
-      }).generate(),
+      endpoint: endpoint.generate(),
     });
   }
 

package/src/features/assistant-message/data/__tests__/AssistantMessage.citations.spec.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it, beforeAll, afterAll } from "vitest";
+import { AssistantMessage } from "../AssistantMessage";
+import { Chunk } from "../../../chunk/data/Chunk";
+import { DataClassRegistry } from "../../../../core/registry/DataClassRegistry";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import { ApiRequestDataTypeInterface } from "../../../../core/interfaces/ApiRequestDataTypeInterface";
+
+const chunkModule: ApiRequestDataTypeInterface = {
+  name: "chunks",
+  model: Chunk,
+} as any;
+
+beforeAll(() => {
+  DataClassRegistry.clear();
+  DataClassRegistry.registerObjectClass(chunkModule, Chunk);
+  ModuleRegistry.register("Chunk", chunkModule);
+});
+
+afterAll(() => {
+  DataClassRegistry.clear();
+});
+
+describe("AssistantMessage citations rehydration", () => {
+  it("rehydrates citations with edge meta (relevance, reason)", () => {
+    const msg = new AssistantMessage();
+    msg.rehydrate({
+      jsonApi: {
+        id: "m1",
+        type: "assistant-messages",
+        attributes: { role: "assistant", content: "answer", position: 1 },
+        relationships: {
+          citations: {
+            data: [{ type: "chunks", id: "c1", meta: { relevance: 0.9, reason: "primary source" } }],
+          },
+        },
+      } as any,
+      included: [
+        {
+          id: "c1",
+          type: "chunks",
+          attributes: { content: "evidence text" },
+          meta: { nodeId: "doc-1", nodeType: "documents" },
+        },
+      ],
+    });
+
+    expect(msg.citations).toHaveLength(1);
+    expect(msg.citations[0].content).toBe("evidence text");
+    expect((msg.citations[0] as any).relevance).toBe(0.9);
+    expect((msg.citations[0] as any).reason).toBe("primary source");
+  });
+
+  it("returns [] when citations relationship is absent", () => {
+    const msg = new AssistantMessage();
+    msg.rehydrate({
+      jsonApi: {
+        id: "m2",
+        type: "assistant-messages",
+        attributes: { role: "assistant", content: "x", position: 0 },
+      } as any,
+      included: [],
+    });
+    expect(msg.citations).toEqual([]);
+  });
+});

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

@@ -5,6 +5,7 @@ import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
 import { JsonApiHydratedDataInterface } from "../../../../core/interfaces/JsonApiHydratedDataInterface";
 import { ApiRequestDataTypeInterface } from "../../../../core/interfaces/ApiRequestDataTypeInterface";
 import { AssistantMessage } from "../AssistantMessage";
+import { Chunk } from "../../../chunk/data/Chunk";
 
 // ---------------------------------------------------------------------------
 // Minimal test-only model — avoids collision with any real app module.
@@ -41,12 +42,19 @@ const assistantModule: ApiRequestDataTypeInterface = {
   model: class {},
 } as any;
 
+const chunkModule: ApiRequestDataTypeInterface = {
+  name: "chunks",
+  model: Chunk,
+} as any;
+
 beforeAll(() => {
   DataClassRegistry.clear();
   DataClassRegistry.registerObjectClass(testAccountModule, TestAccount);
+  DataClassRegistry.registerObjectClass(chunkModule, Chunk);
   ModuleRegistry.register("TestAccount", testAccountModule);
   ModuleRegistry.register("AssistantMessage", assistantMessageModule);
   ModuleRegistry.register("Assistant", assistantModule);
+  ModuleRegistry.register("Chunk", chunkModule);
 });
 
 afterAll(() => {

package/src/features/chunk/ChunkModule.ts

@@ -0,0 +1,18 @@
+import { FileTextIcon } from "lucide-react";
+import { createJsonApiInclusion } from "../../core";
+import { ModuleFactory } from "../../permissions";
+import { Chunk } from "./data/Chunk";
+
+export const ChunkModule = (factory: ModuleFactory) =>
+  factory({
+    pageUrl: "/chunks",
+    name: "chunks",
+    model: Chunk,
+    moduleId: "9b1c2f64-7ea3-4df5-8b2a-91b6a8d0e3a4",
+    icon: FileTextIcon,
+    inclusions: {
+      lists: {
+        fields: [createJsonApiInclusion<Chunk>("chunks", ["content", "nodeId", "nodeType", "imagePath", "source"])],
+      },
+    },
+  });

package/src/features/chunk/data/Chunk.ts

@@ -0,0 +1,49 @@
+import { AbstractApiData, ApiDataInterface, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { resolveReferenceableModules } from "../../assistant/utils/resolveReferenceableModules";
+import { ChunkInterface } from "./ChunkInterface";
+
+export class Chunk extends AbstractApiData implements ChunkInterface {
+  private _content?: string;
+  private _nodeId?: string;
+  private _nodeType?: string;
+  private _imagePath?: string;
+  private _source?: ApiDataInterface;
+
+  get content(): string {
+    return this._content ?? "";
+  }
+  get nodeId(): string | undefined {
+    return this._nodeId;
+  }
+  get nodeType(): string | undefined {
+    return this._nodeType;
+  }
+  get imagePath(): string | undefined {
+    return this._imagePath;
+  }
+  get source(): ApiDataInterface | undefined {
+    return this._source;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+    const attrs = data.jsonApi.attributes ?? {};
+    const meta = data.jsonApi.meta ?? {};
+    this._content = attrs.content;
+    this._nodeId = meta.nodeId ?? attrs.nodeId;
+    this._nodeType = meta.nodeType ?? attrs.nodeType;
+    this._imagePath = attrs.imagePath;
+
+    const src = this._readIncludedPolymorphic<ApiDataInterface>(data, "source", resolveReferenceableModules());
+    this._source = Array.isArray(src) ? src[0] : src;
+    return this;
+  }
+
+  createJsonApi() {
+    // Chunks are read-only from the assistant context. Provide a minimal stub.
+    return {
+      data: { type: Modules.Chunk.name, id: this.id, attributes: {}, relationships: {} },
+      included: [],
+    };
+  }
+}

package/src/features/chunk/data/ChunkInput.ts

@@ -0,0 +1,3 @@
+export type ChunkInput = {
+  id: string;
+};