@carlonicora/nextjs-jsonapi 1.77.2 → 1.78.0

package/src/features/assistant/contexts/__tests__/AssistantContext.spec.tsx

@@ -0,0 +1,375 @@
+import { describe, it, expect, vi, beforeAll, beforeEach } from "vitest";
+import { renderHook, act, waitFor } from "@testing-library/react";
+import { AssistantProvider, useAssistantContext } from "../AssistantContext";
+import { AssistantService } from "../../data/AssistantService";
+import { AssistantMessageService } from "../../../assistant-message/data/AssistantMessageService";
+import { useSocketContext } from "../../../../contexts/SocketContext";
+import type { JsonApiHydratedDataInterface } from "../../../../core";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import { DataClassRegistry } from "../../../../core/registry/DataClassRegistry";
+import { AssistantMessage } from "../../../assistant-message/data/AssistantMessage";
+import { Assistant } from "../../data/Assistant";
+
+vi.mock("../../../../contexts/SocketContext", () => ({
+  useSocketContext: vi.fn(() => ({ socket: null, isConnected: false })),
+}));
+
+function wrapper({ children }: { children: React.ReactNode }) {
+  return <AssistantProvider>{children}</AssistantProvider>;
+}
+
+function buildAssistantStub({ id, title = "Stub" }: { id: string; title?: string }) {
+  return { id, title, messageCount: 0, type: "assistants", createdAt: new Date(), updatedAt: new Date() } as any;
+}
+
+function buildAssistantDehydrated({
+  id,
+  title = "Stub",
+}: {
+  id: string;
+  title?: string;
+}): JsonApiHydratedDataInterface {
+  return {
+    jsonApi: {
+      type: "assistants",
+      id,
+      attributes: { title, messageCount: 0 },
+    },
+    included: [],
+  };
+}
+
+function buildMessageStub({ role, content = "hi" }: { role: "user" | "assistant"; content?: string }) {
+  return { role, content, position: 0, type: "assistant-messages", id: Math.random().toString(36).slice(2) } as any;
+}
+
+describe("AssistantContext", () => {
+  beforeAll(() => {
+    const assistantMessageModule = { name: "assistant-messages", model: AssistantMessage } as any;
+    const assistantModule = { name: "assistants", model: Assistant } as any;
+    ModuleRegistry.register("AssistantMessage", assistantMessageModule);
+    ModuleRegistry.register("Assistant", assistantModule);
+    DataClassRegistry.registerObjectClass(assistantMessageModule, AssistantMessage);
+    DataClassRegistry.registerObjectClass(assistantModule, Assistant);
+  });
+
+  beforeEach(() => {
+    vi.mocked(useSocketContext).mockReturnValue({ socket: null, isConnected: false } as any);
+    AssistantService.findMany = vi.fn().mockResolvedValue([]);
+  });
+
+  it("initial state: no assistant, empty messages, not sending", () => {
+    const { result } = renderHook(() => useAssistantContext(), { wrapper });
+    expect(result.current.assistant).toBeUndefined();
+    expect(result.current.messages).toEqual([]);
+    expect(result.current.sending).toBe(false);
+  });
+
+  it("sendMessage with no assistant: creates one and swaps URL via replaceState", async () => {
+    const replaceState = vi.spyOn(window.history, "replaceState").mockImplementation(() => {});
+    const created = buildAssistantStub({ id: "a-1", title: "Test" });
+    const userMsg = buildMessageStub({ role: "user" });
+    const assistantMsg = buildMessageStub({ role: "assistant" });
+    AssistantService.create = vi.fn().mockResolvedValue(created);
+    AssistantMessageService.findByAssistant = vi.fn().mockResolvedValue([userMsg, assistantMsg]);
+
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => <AssistantProvider>{children}</AssistantProvider>,
+    });
+    await act(async () => {
+      await result.current.sendMessage("first question");
+    });
+
+    expect(AssistantService.create).toHaveBeenCalledWith({ firstMessage: "first question" });
+    expect(AssistantMessageService.findByAssistant).toHaveBeenCalledWith({ assistantId: "a-1" });
+    expect(result.current.assistant?.id).toBe("a-1");
+    expect(result.current.messages).toHaveLength(2);
+    expect(replaceState).toHaveBeenCalledWith(null, "", "/assistants/a-1");
+  });
+
+  it("sendMessage with existing assistant: appends [user, assistant]", async () => {
+    const existing = buildAssistantDehydrated({ id: "a-2", title: "Existing" });
+    AssistantService.appendMessage = vi
+      .fn()
+      .mockResolvedValue([
+        buildMessageStub({ role: "user", content: "follow-up" }),
+        buildMessageStub({ role: "assistant", content: "reply" }),
+      ]);
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => <AssistantProvider dehydratedAssistant={existing}>{children}</AssistantProvider>,
+    });
+    await act(async () => {
+      await result.current.sendMessage("follow-up");
+    });
+    expect(AssistantService.appendMessage).toHaveBeenCalledWith({ assistantId: "a-2", content: "follow-up" });
+    expect(result.current.messages.map((m) => m.content)).toEqual(["follow-up", "reply"]);
+  });
+
+  it("selectThread loads messages and replaces URL", async () => {
+    const target = buildAssistantStub({ id: "a-3", title: "Target" });
+    AssistantService.findOne = vi.fn().mockResolvedValue(target);
+    AssistantMessageService.findByAssistant = vi.fn().mockResolvedValue([buildMessageStub({ role: "user" })]);
+    const replaceState = vi.spyOn(window.history, "replaceState").mockImplementation(() => {});
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => <AssistantProvider>{children}</AssistantProvider>,
+    });
+    await act(async () => {
+      await result.current.selectThread("a-3");
+    });
+    expect(AssistantService.findOne).toHaveBeenCalledWith({ id: "a-3" });
+    expect(AssistantMessageService.findByAssistant).toHaveBeenCalledWith({ assistantId: "a-3" });
+    expect(result.current.assistant?.id).toBe("a-3");
+    expect(result.current.messages).toHaveLength(1);
+    expect(replaceState).toHaveBeenCalledWith(null, "", "/assistants/a-3");
+  });
+
+  it("renameThread calls the service + updates active assistant title", async () => {
+    AssistantService.rename = vi.fn().mockResolvedValue(undefined);
+    const active = buildAssistantDehydrated({ id: "a-1", title: "Old" });
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => <AssistantProvider dehydratedAssistant={active}>{children}</AssistantProvider>,
+    });
+    await act(async () => {
+      await result.current.renameThread("a-1", "New");
+    });
+    expect(AssistantService.rename).toHaveBeenCalledWith({ id: "a-1", title: "New" });
+    expect(result.current.assistant?.title).toBe("New");
+  });
+
+  it("deleteThread calls the service + clears active if deleted was active", async () => {
+    AssistantService.delete = vi.fn().mockResolvedValue(undefined);
+    const active = buildAssistantDehydrated({ id: "a-1", title: "A" });
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => <AssistantProvider dehydratedAssistant={active}>{children}</AssistantProvider>,
+    });
+    await act(async () => {
+      await result.current.deleteThread("a-1");
+    });
+    expect(AssistantService.delete).toHaveBeenCalledWith({ id: "a-1" });
+    expect(result.current.assistant).toBeUndefined();
+    expect(result.current.messages).toEqual([]);
+  });
+
+  it("startNew clears the active assistant, messages, failed ids, and resets URL to /assistants", async () => {
+    const replaceState = vi.spyOn(window.history, "replaceState").mockImplementation(() => {});
+    const existing = buildAssistantDehydrated({ id: "a-9", title: "Hydrated" });
+    const msg = buildMessageStub({ role: "user", content: "hi" });
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => (
+        <AssistantProvider
+          dehydratedAssistant={existing}
+          dehydratedMessages={[
+            {
+              jsonApi: {
+                type: "assistant-messages",
+                id: msg.id,
+                attributes: { role: "user", content: "hi", position: 0 },
+              },
+              included: [],
+            },
+          ]}
+        >
+          {children}
+        </AssistantProvider>
+      ),
+    });
+
+    // Seed a failed message id by forcing an append failure.
+    AssistantService.appendMessage = vi.fn().mockRejectedValue(new Error("boom"));
+    await act(async () => {
+      await result.current.sendMessage("will fail").catch(() => {});
+    });
+    expect(result.current.failedMessageIds.size).toBeGreaterThan(0);
+    expect(result.current.assistant?.id).toBe("a-9");
+    expect(result.current.messages.length).toBeGreaterThan(0);
+
+    act(() => {
+      result.current.startNew();
+    });
+
+    expect(result.current.assistant).toBeUndefined();
+    expect(result.current.messages).toEqual([]);
+    expect(result.current.failedMessageIds.size).toBe(0);
+    expect(replaceState).toHaveBeenCalledWith(null, "", "/assistants");
+  });
+
+  it("loads threads on mount", async () => {
+    const t1 = buildAssistantStub({ id: "t1", title: "T1" });
+    AssistantService.findMany = vi.fn().mockResolvedValue([t1]);
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => <AssistantProvider>{children}</AssistantProvider>,
+    });
+    await waitFor(() => expect(result.current.threads).toEqual([t1]));
+  });
+
+  it("subscribes to assistant:status while sending and unsubscribes after", async () => {
+    const handlers: Record<string, (payload: any) => void> = {};
+    const socket = {
+      on: vi.fn((evt: string, h: any) => {
+        handlers[evt] = h;
+      }),
+      off: vi.fn((evt: string) => {
+        delete handlers[evt];
+      }),
+    };
+    vi.mocked(useSocketContext).mockReturnValue({ socket, isConnected: true } as any);
+
+    const created = buildAssistantStub({ id: "a-4", title: "Stub" });
+    AssistantService.create = vi
+      .fn()
+      .mockImplementation(() => new Promise((resolve) => setTimeout(() => resolve(created), 20)));
+    AssistantMessageService.findByAssistant = vi.fn().mockResolvedValue([]);
+
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => <AssistantProvider>{children}</AssistantProvider>,
+    });
+    let sendPromise: Promise<void>;
+    await act(async () => {
+      sendPromise = result.current.sendMessage("go");
+      // allow subscription to register before the create resolves
+      await Promise.resolve();
+    });
+    await waitFor(() => expect(socket.on).toHaveBeenCalledWith("assistant:status", expect.any(Function)));
+    handlers["assistant:status"]?.({ assistantId: "a-4", status: "Searching accounts", at: new Date().toISOString() });
+    await act(async () => {
+      await sendPromise!;
+    });
+    expect(socket.off).toHaveBeenCalledWith("assistant:status", expect.any(Function));
+  });
+
+  it("exposes an empty failedMessageIds set and a retrySend callback", () => {
+    const { result } = renderHook(() => useAssistantContext(), { wrapper });
+    expect(result.current.failedMessageIds).toBeInstanceOf(Set);
+    expect(result.current.failedMessageIds.size).toBe(0);
+    expect(typeof result.current.retrySend).toBe("function");
+  });
+
+  it("sendMessage (existing assistant): shows the user bubble synchronously before the server responds", async () => {
+    const existing = buildAssistantDehydrated({ id: "a-2", title: "Existing" });
+    let resolveAppend!: (value: any) => void;
+    AssistantService.appendMessage = vi.fn().mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          resolveAppend = resolve;
+        }),
+    );
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => <AssistantProvider dehydratedAssistant={existing}>{children}</AssistantProvider>,
+    });
+
+    let sendPromise: Promise<void>;
+    act(() => {
+      sendPromise = result.current.sendMessage("follow-up");
+    });
+
+    // Before the server responds, the optimistic user bubble must be visible.
+    expect(result.current.messages.map((m) => m.content)).toContain("follow-up");
+    expect(result.current.messages.some((m) => m.id.startsWith("tmp-") && m.role === "user")).toBe(true);
+    expect(result.current.sending).toBe(true);
+
+    await act(async () => {
+      resolveAppend([
+        buildMessageStub({ role: "user", content: "follow-up" }),
+        buildMessageStub({ role: "assistant", content: "reply" }),
+      ]);
+      await sendPromise!;
+    });
+
+    // After reconciliation, no tmp-* remains, and server messages are appended.
+    expect(result.current.messages.some((m) => m.id.startsWith("tmp-"))).toBe(false);
+    expect(result.current.messages.map((m) => m.content)).toEqual(["follow-up", "reply"]);
+    expect(result.current.sending).toBe(false);
+  });
+
+  it("sendMessage (no assistant): shows the user bubble synchronously before create resolves", async () => {
+    const replaceState = vi.spyOn(window.history, "replaceState").mockImplementation(() => {});
+    const created = buildAssistantStub({ id: "a-1", title: "Test" });
+    const userMsg = buildMessageStub({ role: "user", content: "first question" });
+    const assistantMsg = buildMessageStub({ role: "assistant", content: "answer" });
+
+    let resolveCreate!: (value: any) => void;
+    AssistantService.create = vi.fn().mockImplementation(
+      () =>
+        new Promise((resolve) => {
+          resolveCreate = resolve;
+        }),
+    );
+    AssistantMessageService.findByAssistant = vi.fn().mockResolvedValue([userMsg, assistantMsg]);
+
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => <AssistantProvider>{children}</AssistantProvider>,
+    });
+
+    let sendPromise: Promise<void>;
+    act(() => {
+      sendPromise = result.current.sendMessage("first question");
+    });
+
+    // Before the server responds: thread has exactly the optimistic user bubble.
+    expect(result.current.messages).toHaveLength(1);
+    expect(result.current.messages[0].id.startsWith("tmp-")).toBe(true);
+    expect(result.current.messages[0].content).toBe("first question");
+    expect(result.current.assistant).toBeUndefined();
+    expect(result.current.sending).toBe(true);
+
+    await act(async () => {
+      resolveCreate(created);
+      await sendPromise!;
+    });
+
+    // After reconciliation: assistant set, URL replaced, server messages only.
+    expect(result.current.assistant?.id).toBe("a-1");
+    expect(result.current.messages.some((m) => m.id.startsWith("tmp-"))).toBe(false);
+    expect(result.current.messages).toHaveLength(2);
+    expect(replaceState).toHaveBeenCalledWith(null, "", "/assistants/a-1");
+  });
+
+  it("sendMessage failure: optimistic message stays and its id lands in failedMessageIds", async () => {
+    const existing = buildAssistantDehydrated({ id: "a-x", title: "Ex" });
+    AssistantService.appendMessage = vi.fn().mockRejectedValue(new Error("boom"));
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => <AssistantProvider dehydratedAssistant={existing}>{children}</AssistantProvider>,
+    });
+
+    await act(async () => {
+      await result.current.sendMessage("oops").catch(() => {});
+    });
+
+    const optimistic = result.current.messages.find((m) => m.id.startsWith("tmp-"));
+    expect(optimistic).toBeDefined();
+    expect(optimistic!.content).toBe("oops");
+    expect(result.current.failedMessageIds.has(optimistic!.id)).toBe(true);
+    expect(result.current.sending).toBe(false);
+  });
+
+  it("retrySend: clears the failed id, removes the old tmp message, and resends the content", async () => {
+    const existing = buildAssistantDehydrated({ id: "a-y", title: "Ey" });
+    const appendMock = vi
+      .fn()
+      .mockRejectedValueOnce(new Error("fail-1"))
+      .mockResolvedValueOnce([
+        buildMessageStub({ role: "user", content: "retry-me" }),
+        buildMessageStub({ role: "assistant", content: "ok" }),
+      ]);
+    AssistantService.appendMessage = appendMock;
+
+    const { result } = renderHook(() => useAssistantContext(), {
+      wrapper: ({ children }) => <AssistantProvider dehydratedAssistant={existing}>{children}</AssistantProvider>,
+    });
+
+    await act(async () => {
+      await result.current.sendMessage("retry-me").catch(() => {});
+    });
+    const failedId = [...result.current.failedMessageIds][0];
+    expect(failedId).toBeDefined();
+
+    await act(async () => {
+      await result.current.retrySend(failedId!);
+    });
+
+    expect(result.current.failedMessageIds.has(failedId!)).toBe(false);
+    expect(result.current.messages.some((m) => m.id.startsWith("tmp-"))).toBe(false);
+    expect(result.current.messages.map((m) => m.content)).toEqual(["retry-me", "ok"]);
+    expect(appendMock).toHaveBeenCalledTimes(2);
+  });
+});

package/src/features/assistant/data/Assistant.ts

@@ -0,0 +1,37 @@
+import { AbstractApiData, JsonApiHydratedDataInterface, Modules } from "../../../core";
+import { AssistantInput, AssistantInterface } from "./AssistantInterface";
+
+export class Assistant extends AbstractApiData implements AssistantInterface {
+  private _title?: string;
+  private _messageCount?: number;
+
+  get title(): string {
+    return this._title ?? "";
+  }
+
+  get messageCount(): number {
+    return this._messageCount ?? 0;
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+    this._title = data.jsonApi.attributes?.title;
+    const fromMeta = data.jsonApi.meta?.messageCount;
+    const fromAttrs = data.jsonApi.attributes?.messageCount;
+    this._messageCount = typeof fromMeta === "number" ? fromMeta : typeof fromAttrs === "number" ? fromAttrs : 0;
+    return this;
+  }
+
+  createJsonApi(data: AssistantInput) {
+    return {
+      data: {
+        type: Modules.Assistant.name,
+        attributes: {
+          content: data.firstMessage,
+          ...(data.title !== undefined ? { title: data.title } : {}),
+        },
+      },
+      included: [],
+    };
+  }
+}

package/src/features/assistant/data/AssistantInterface.ts

@@ -0,0 +1,11 @@
+import { ApiDataInterface } from "../../../core";
+
+export type AssistantInput = {
+  firstMessage: string;
+  title?: string;
+};
+
+export interface AssistantInterface extends ApiDataInterface {
+  get title(): string;
+  get messageCount(): number;
+}

package/src/features/assistant/data/AssistantService.ts

@@ -0,0 +1,79 @@
+import { AbstractService, EndpointCreator, HttpMethod, Modules } from "../../../core";
+import { AssistantInput, AssistantInterface } from "./AssistantInterface";
+import { AssistantMessageInterface } from "../../assistant-message/data/AssistantMessageInterface";
+
+export class AssistantService extends AbstractService {
+  static async findOne(params: { id: string }): Promise<AssistantInterface> {
+    return this.callApi<AssistantInterface>({
+      type: Modules.Assistant,
+      method: HttpMethod.GET,
+      endpoint: new EndpointCreator({ endpoint: Modules.Assistant, id: params.id }).generate(),
+    });
+  }
+
+  static async findMany(params: { fetchAll?: boolean } = {}): Promise<AssistantInterface[]> {
+    const endpoint = new EndpointCreator({ endpoint: Modules.Assistant });
+    if (params.fetchAll) endpoint.addAdditionalParam("fetchAll", "true");
+    return this.callApi({
+      type: Modules.Assistant,
+      method: HttpMethod.GET,
+      endpoint: endpoint.generate(),
+    });
+  }
+
+  static async create(params: AssistantInput): Promise<AssistantInterface> {
+    return this.callApi({
+      type: Modules.Assistant,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({ endpoint: Modules.Assistant }).generate(),
+      input: params,
+    });
+  }
+
+  /**
+   * Sends a new user message to an existing assistant thread. The agent turn
+   * runs synchronously; the response is a two-element list: [user, assistant].
+   */
+  static async appendMessage(params: { assistantId: string; content: string }): Promise<AssistantMessageInterface[]> {
+    return this.callApi<AssistantMessageInterface[]>({
+      type: Modules.AssistantMessage,
+      method: HttpMethod.POST,
+      endpoint: new EndpointCreator({
+        endpoint: Modules.Assistant,
+        id: params.assistantId,
+        childEndpoint: Modules.AssistantMessage,
+      }).generate(),
+      input: {
+        data: {
+          type: Modules.AssistantMessage.name,
+          attributes: { content: params.content },
+        },
+      },
+      overridesJsonApiCreation: true,
+    });
+  }
+
+  static async rename(params: { id: string; title: string }): Promise<void> {
+    await this.callApi({
+      type: Modules.Assistant,
+      method: HttpMethod.PATCH,
+      endpoint: new EndpointCreator({ endpoint: Modules.Assistant, id: params.id }).generate(),
+      input: {
+        data: {
+          type: Modules.Assistant.name,
+          id: params.id,
+          attributes: { title: params.title },
+        },
+      },
+      overridesJsonApiCreation: true,
+    });
+  }
+
+  static async delete(params: { id: string }): Promise<void> {
+    await this.callApi({
+      type: Modules.Assistant,
+      method: HttpMethod.DELETE,
+      endpoint: new EndpointCreator({ endpoint: Modules.Assistant, id: params.id }).generate(),
+    });
+  }
+}

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

@@ -0,0 +1,3 @@
+export * from "./Assistant";
+export * from "./AssistantInterface";
+export * from "./AssistantService";

package/src/features/assistant/index.ts

@@ -0,0 +1,2 @@
+export * from "./AssistantModule";
+export * from "./data";

package/src/features/assistant/utils/__tests__/groupThreadsByBucket.spec.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from "vitest";
+import { groupThreadsByBucket } from "../groupThreadsByBucket";
+
+describe("groupThreadsByBucket", () => {
+  beforeEach(() => vi.useFakeTimers().setSystemTime(new Date("2026-04-22T12:00:00Z")));
+  afterEach(() => vi.useRealTimers());
+
+  it("buckets today, thisWeek, earlier by updatedAt", () => {
+    const today = { id: "1", updatedAt: new Date("2026-04-22T09:00:00Z") } as any;
+    const weekAgo2 = { id: "2", updatedAt: new Date("2026-04-20T09:00:00Z") } as any;
+    const earlier = { id: "3", updatedAt: new Date("2026-03-01T09:00:00Z") } as any;
+    const grouped = groupThreadsByBucket([today, weekAgo2, earlier]);
+    expect(grouped.today).toEqual([today]);
+    expect(grouped.thisWeek).toEqual([weekAgo2]);
+    expect(grouped.earlier).toEqual([earlier]);
+  });
+
+  it("sorts each bucket by updatedAt desc", () => {
+    const a = { id: "a", updatedAt: new Date("2026-04-22T09:00:00Z") } as any;
+    const b = { id: "b", updatedAt: new Date("2026-04-22T10:00:00Z") } as any;
+    const grouped = groupThreadsByBucket([a, b]);
+    expect(grouped.today).toEqual([b, a]);
+  });
+});

package/src/features/assistant/utils/__tests__/resolveReferenceableModules.spec.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { AbstractApiData } from "../../../../core/abstracts/AbstractApiData";
+import { DataClassRegistry } from "../../../../core/registry/DataClassRegistry";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import { ApiRequestDataTypeInterface } from "../../../../core/interfaces/ApiRequestDataTypeInterface";
+import { JsonApiHydratedDataInterface } from "../../../../core/interfaces/JsonApiHydratedDataInterface";
+import { resolveReferenceableModules } from "../resolveReferenceableModules";
+
+// ---------------------------------------------------------------------------
+// Test-only model WITH identifierFields (default: ["name"]) — should be included
+// ---------------------------------------------------------------------------
+class WithIdentifier extends AbstractApiData {
+  static identifierFields: string[] = ["name"];
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+    return this;
+  }
+
+  createJsonApi(_data?: any): any {
+    return {};
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test-only model WITHOUT identifierFields (forced to []) — should be excluded
+// ---------------------------------------------------------------------------
+class WithoutIdentifier extends AbstractApiData {
+  static identifierFields: string[] = [];
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+    return this;
+  }
+
+  createJsonApi(_data?: any): any {
+    return {};
+  }
+}
+
+const withIdentifierModule: ApiRequestDataTypeInterface = {
+  name: "test-with-identifier",
+  model: WithIdentifier,
+} as any;
+
+const withoutIdentifierModule: ApiRequestDataTypeInterface = {
+  name: "test-without-identifier",
+  model: WithoutIdentifier,
+} as any;
+
+// ---------------------------------------------------------------------------
+// Setup / teardown
+// ---------------------------------------------------------------------------
+beforeAll(() => {
+  DataClassRegistry.clear();
+  DataClassRegistry.registerObjectClass(withIdentifierModule, WithIdentifier);
+  DataClassRegistry.registerObjectClass(withoutIdentifierModule, WithoutIdentifier);
+  ModuleRegistry.register("TestWithIdentifier", withIdentifierModule);
+  ModuleRegistry.register("TestWithoutIdentifier", withoutIdentifierModule);
+});
+
+afterAll(() => {
+  DataClassRegistry.clear();
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe("resolveReferenceableModules", () => {
+  it("returns an array of ApiRequestDataTypeInterface-shaped entries (has .name: string)", () => {
+    const result = resolveReferenceableModules();
+
+    expect(Array.isArray(result)).toBe(true);
+    for (const entry of result) {
+      expect(typeof entry.name).toBe("string");
+    }
+  });
+
+  it("includes modules whose model class has non-empty identifierFields", () => {
+    const result = resolveReferenceableModules();
+
+    const names = result.map((m) => m.name);
+    expect(names).toContain("test-with-identifier");
+  });
+
+  it("excludes modules whose model class has empty identifierFields", () => {
+    const result = resolveReferenceableModules();
+
+    const names = result.map((m) => m.name);
+    expect(names).not.toContain("test-without-identifier");
+  });
+});

package/src/features/assistant/utils/groupThreadsByBucket.ts

@@ -0,0 +1,26 @@
+import type { AssistantInterface } from "../data/AssistantInterface";
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+export function groupThreadsByBucket(threads: AssistantInterface[]): {
+  today: AssistantInterface[];
+  thisWeek: AssistantInterface[];
+  earlier: AssistantInterface[];
+} {
+  const now = new Date();
+  const startOfToday = new Date(now.getFullYear(), now.getMonth(), now.getDate()).getTime();
+  const startOfWeek = startOfToday - 7 * MS_PER_DAY;
+
+  const sorted = [...threads].sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime());
+
+  const today: AssistantInterface[] = [];
+  const thisWeek: AssistantInterface[] = [];
+  const earlier: AssistantInterface[] = [];
+  for (const t of sorted) {
+    const ts = t.updatedAt.getTime();
+    if (ts >= startOfToday) today.push(t);
+    else if (ts >= startOfWeek) thisWeek.push(t);
+    else earlier.push(t);
+  }
+  return { today, thisWeek, earlier };
+}

package/src/features/assistant/utils/resolveReferenceableModules.ts

@@ -0,0 +1,14 @@
+import type { ApiRequestDataTypeInterface } from "../../../core/interfaces/ApiRequestDataTypeInterface";
+import { ModuleRegistry } from "../../../core/registry/ModuleRegistry";
+
+/**
+ * Returns every registered Module whose model class has a non-empty `identifierFields`
+ * (so `entity.identifier` produces a meaningful string). Lazy — reads at call time so
+ * modules registered after import-time are picked up.
+ */
+export function resolveReferenceableModules(): ApiRequestDataTypeInterface[] {
+  return ModuleRegistry.getAll().filter((m) => {
+    const cls = m.model as any;
+    return cls && Array.isArray(cls.identifierFields) && cls.identifierFields.length > 0;
+  });
+}