@stigmer/react 3.7.0 → 3.9.0

package/src/conversation/__tests__/conversationPresentation.test.ts

@@ -0,0 +1,289 @@
+import { describe, it, expect } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { timestampFromDate } from "@bufbuild/protobuf/wkt";
+import {
+  ChannelConversationSchema,
+  ConversationControl,
+  ConversationItemAuthor,
+  ConversationLane,
+  ConversationTimelineItemSchema,
+  type ConversationTimelineItem,
+} from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+import { ChannelDeliveryStatus } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/delivery_pb";
+import { ChannelReceiptState } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/outbound_pb";
+import {
+  authorKindOf,
+  awaitingIndicatorOf,
+  compareTimelineItemsNewestFirst,
+  conversationContactOf,
+  conversationLabelOf,
+  inboundPlaceholderOf,
+  isInternalItem,
+  outboundItemIdOf,
+  receiptOf,
+  sendAttemptOf,
+  serviceWindowOf,
+} from "../conversationPresentation";
+
+function item(fields: Parameters<typeof create<typeof ConversationTimelineItemSchema>>[1]) {
+  return create(ConversationTimelineItemSchema, fields);
+}
+
+describe("authorKindOf", () => {
+  it("maps every wire author onto the render vocabulary", () => {
+    expect(authorKindOf(item({ author: ConversationItemAuthor.author_customer }))).toBe("customer");
+    expect(authorKindOf(item({ author: ConversationItemAuthor.author_agent }))).toBe("agent");
+    expect(authorKindOf(item({ author: ConversationItemAuthor.author_teammate }))).toBe("teammate");
+    expect(authorKindOf(item({ author: ConversationItemAuthor.author_platform }))).toBe("platform");
+  });
+
+  it("answers unknown for the unspecified author rather than guessing", () => {
+    expect(authorKindOf(item({}))).toBe("unknown");
+  });
+});
+
+describe("isInternalItem", () => {
+  it("flags internal-lane items and only those", () => {
+    expect(isInternalItem(item({ lane: ConversationLane.lane_internal }))).toBe(true);
+    expect(isInternalItem(item({ lane: ConversationLane.lane_public }))).toBe(false);
+    expect(isInternalItem(item({}))).toBe(false);
+  });
+});
+
+describe("awaitingIndicatorOf (DD-011 D-a: strength maps the holder)", () => {
+  it("renders strongly when a human holds an awaiting conversation — the agent will not answer", () => {
+    expect(
+      awaitingIndicatorOf(
+        create(ChannelConversationSchema, {
+          awaitingReply: true,
+          control: ConversationControl.control_human,
+        }),
+      ),
+    ).toBe("strong");
+  });
+
+  it("renders mutedly when the agent holds an awaiting conversation — an answer is on its way", () => {
+    expect(
+      awaitingIndicatorOf(
+        create(ChannelConversationSchema, {
+          awaitingReply: true,
+          control: ConversationControl.control_agent,
+        }),
+      ),
+    ).toBe("muted");
+    // The unspecified holder defaults to the agent (proto3 zero value).
+    expect(
+      awaitingIndicatorOf(create(ChannelConversationSchema, { awaitingReply: true })),
+    ).toBe("muted");
+  });
+
+  it("renders nothing once the customer is answered, whoever holds it", () => {
+    expect(
+      awaitingIndicatorOf(
+        create(ChannelConversationSchema, {
+          control: ConversationControl.control_human,
+        }),
+      ),
+    ).toBeNull();
+    expect(awaitingIndicatorOf(create(ChannelConversationSchema, {}))).toBeNull();
+  });
+});
+
+describe("outboundItemIdOf", () => {
+  it("names the timeline item an accepted staff reply appears under (the ob: namespace)", () => {
+    expect(outboundItemIdOf("obm_1")).toBe("ob:obm_1");
+  });
+});
+
+describe("the two status axes (DD-004 D-d: never collapsed)", () => {
+  it("maps the send attempt independently of the receipt", () => {
+    expect(sendAttemptOf(item({ deliveryStatus: ChannelDeliveryStatus.pending }))).toBe("pending");
+    expect(sendAttemptOf(item({ deliveryStatus: ChannelDeliveryStatus.delivering }))).toBe("delivering");
+    expect(sendAttemptOf(item({ deliveryStatus: ChannelDeliveryStatus.delivered }))).toBe("delivered");
+    expect(sendAttemptOf(item({ deliveryStatus: ChannelDeliveryStatus.failed }))).toBe("failed");
+    expect(sendAttemptOf(item({ deliveryStatus: ChannelDeliveryStatus.suppressed }))).toBe("suppressed");
+    expect(sendAttemptOf(item({}))).toBeNull();
+  });
+
+  it("maps the receipt independently of the send attempt", () => {
+    expect(receiptOf(item({ receiptState: ChannelReceiptState.receipt_sent }))).toBe("sent");
+    expect(receiptOf(item({ receiptState: ChannelReceiptState.receipt_delivered }))).toBe("delivered");
+    expect(receiptOf(item({ receiptState: ChannelReceiptState.receipt_read }))).toBe("read");
+    expect(receiptOf(item({ receiptState: ChannelReceiptState.receipt_failed }))).toBe("failed");
+    expect(receiptOf(item({}))).toBeNull();
+  });
+
+  it("represents the provider-accepted-then-failed item: delivered attempt, failed receipt", () => {
+    // The combination a collapsed single status cannot express — "we
+    // handed it to the provider" AND "it never reached the phone".
+    const acceptedThenFailed = item({
+      deliveryStatus: ChannelDeliveryStatus.delivered,
+      receiptState: ChannelReceiptState.receipt_failed,
+    });
+    expect(sendAttemptOf(acceptedThenFailed)).toBe("delivered");
+    expect(receiptOf(acceptedThenFailed)).toBe("failed");
+  });
+
+  it("keeps inbound items off both axes", () => {
+    const inbound = item({
+      author: ConversationItemAuthor.author_customer,
+      text: "hello",
+    });
+    expect(sendAttemptOf(inbound)).toBeNull();
+    expect(receiptOf(inbound)).toBeNull();
+  });
+});
+
+describe("inboundPlaceholderOf", () => {
+  it("names the known non-text kinds", () => {
+    expect(inboundPlaceholderOf(item({ providerMessageType: "image" }))).toBe("Photo");
+    expect(inboundPlaceholderOf(item({ providerMessageType: "audio" }))).toBe("Voice message");
+    expect(inboundPlaceholderOf(item({ providerMessageType: "document" }))).toBe("Document");
+    expect(inboundPlaceholderOf(item({ providerMessageType: "location" }))).toBe("Location");
+  });
+
+  it("passes an unknown provider kind through verbatim, never re-encoded", () => {
+    expect(inboundPlaceholderOf(item({ providerMessageType: "reaction" })))
+      .toBe("Unsupported message (reaction)");
+  });
+
+  it("needs no placeholder for items with text or without a provider type", () => {
+    expect(inboundPlaceholderOf(item({ text: "hi", providerMessageType: "text" }))).toBeNull();
+    // Empty text + empty type: internal events (attention clears) and
+    // template sends — their copy is the renderer's, not a placeholder.
+    expect(inboundPlaceholderOf(item({}))).toBeNull();
+  });
+});
+
+describe("conversationLabelOf", () => {
+  it("prefers the provider-reported display name", () => {
+    const conversation = create(ChannelConversationSchema, {
+      conversationKey: "15550001111",
+      displayName: "Pat",
+    });
+    expect(conversationLabelOf(conversation, "whatsapp")).toBe("Pat");
+  });
+
+  it("falls back to the key on WhatsApp — a phone number is a real label", () => {
+    const conversation = create(ChannelConversationSchema, {
+      conversationKey: "15550001111",
+    });
+    expect(conversationLabelOf(conversation, "whatsapp")).toBe("15550001111");
+    expect(conversationLabelOf(conversation, null)).toBe("15550001111");
+  });
+
+  it("never shows a Slack thread timestamp as a name", () => {
+    const conversation = create(ChannelConversationSchema, {
+      conversationKey: "1723012345.678900",
+    });
+    expect(conversationLabelOf(conversation, "slack")).toBe("Slack thread");
+  });
+});
+
+describe("conversationContactOf", () => {
+  it("surfaces the WhatsApp number a display name would otherwise hide (F-17)", () => {
+    const conversation = create(ChannelConversationSchema, {
+      conversationKey: "15550001111",
+      displayName: "Pat",
+    });
+    // Verbatim wire value — no fabricated "+" prefix.
+    expect(conversationContactOf(conversation, "whatsapp")).toBe("15550001111");
+  });
+
+  it("adds nothing when the label already shows the key", () => {
+    const conversation = create(ChannelConversationSchema, {
+      conversationKey: "15550001111",
+    });
+    expect(conversationContactOf(conversation, "whatsapp")).toBeNull();
+  });
+
+  it("answers null for keys that are not reachable addresses", () => {
+    const slackThread = create(ChannelConversationSchema, {
+      conversationKey: "1723012345.678900",
+      displayName: "deploy question",
+    });
+    expect(conversationContactOf(slackThread, "slack")).toBeNull();
+    // An unknown provider shows nothing rather than guessing that its
+    // key is an address.
+    expect(conversationContactOf(slackThread, null)).toBeNull();
+  });
+});
+
+describe("serviceWindowOf (DD-014 D-a: client-derived, WhatsApp-only)", () => {
+  const NOW = new Date("2026-08-08T12:00:00Z");
+  const lastWrote = (iso: string) =>
+    create(ChannelConversationSchema, {
+      conversationKey: "15550001111",
+      lastCustomerMessageAt: timestampFromDate(new Date(iso)),
+    });
+
+  it("answers open inside the 24-hour window", () => {
+    expect(serviceWindowOf(lastWrote("2026-08-08T11:59:00Z"), "whatsapp", NOW)).toBe("open");
+    // One millisecond inside the boundary.
+    expect(serviceWindowOf(lastWrote("2026-08-07T12:00:00.001Z"), "whatsapp", NOW)).toBe(
+      "open",
+    );
+  });
+
+  it("answers closed at exactly 24 hours — the tie closes because our anchor already lags Meta's", () => {
+    // The stored anchor is the platform's receipt instant, minutes AFTER
+    // Meta's own clock started the window, so the estimate inherently
+    // errs toward claiming open too long. Closing the tie is the honest
+    // offset; the warn-never-block posture (DD-014 D-b) makes either
+    // direction safe to render.
+    expect(serviceWindowOf(lastWrote("2026-08-07T12:00:00Z"), "whatsapp", NOW)).toBe("closed");
+    expect(serviceWindowOf(lastWrote("2026-08-06T09:00:00Z"), "whatsapp", NOW)).toBe("closed");
+  });
+
+  it("makes no claim without a customer message — that conversation is the composer's disabled branch", () => {
+    expect(serviceWindowOf(create(ChannelConversationSchema, {}), "whatsapp", NOW)).toBeNull();
+  });
+
+  it("makes no claim for providers without a window", () => {
+    const stale = lastWrote("2026-08-01T09:00:00Z");
+    expect(serviceWindowOf(stale, "slack", NOW)).toBeNull();
+    expect(serviceWindowOf(stale, null, NOW)).toBeNull();
+  });
+
+  it("reads a future-dated customer message as open instead of misfiring on clock skew", () => {
+    expect(serviceWindowOf(lastWrote("2026-08-08T12:05:00Z"), "whatsapp", NOW)).toBe("open");
+  });
+});
+
+describe("compareTimelineItemsNewestFirst", () => {
+  const at = (iso: string) => timestampFromDate(new Date(iso));
+
+  it("orders by instant descending", () => {
+    const older = item({ itemId: "wa:1", at: at("2026-08-07T09:00:00Z") });
+    const newer = item({ itemId: "dl:2", at: at("2026-08-07T09:00:05Z") });
+    expect([older, newer].sort(compareTimelineItemsNewestFirst)).toEqual([newer, older]);
+  });
+
+  it("orders sub-second instants by nanos — the 007/D7 string-inversion trap is structurally absent", () => {
+    const wholeSecond = item({ itemId: "wa:1", at: at("2026-08-07T09:00:00.000Z") });
+    const midSecond = item({ itemId: "wa:2", at: at("2026-08-07T09:00:00.123Z") });
+    // As RFC-3339 TEXT, "..:00.123Z" sorts BEFORE "..:00Z" — the
+    // inversion the server corrects by parsing. This comparator works on
+    // seconds+nanos, so chronology holds by construction.
+    expect([midSecond, wholeSecond].sort(compareTimelineItemsNewestFirst)).toEqual([
+      midSecond,
+      wholeSecond,
+    ]);
+  });
+
+  it("breaks instant ties by item id descending — the server's exact tiebreak", () => {
+    const instant = at("2026-08-07T09:00:00Z");
+    const a = item({ itemId: "dl:aaa", at: instant });
+    const b = item({ itemId: "wa:bbb", at: instant });
+    expect([a, b].sort(compareTimelineItemsNewestFirst)).toEqual([b, a]);
+  });
+
+  it("sorts an instant-less defensive item oldest instead of crashing", () => {
+    const bare = item({ itemId: "wa:bare" });
+    const dated = item({ itemId: "wa:dated", at: at("2026-08-07T09:00:00Z") });
+    const sorted: ConversationTimelineItem[] = [bare, dated].sort(
+      compareTimelineItemsNewestFirst,
+    );
+    expect(sorted[0]).toBe(dated);
+  });
+});

package/src/conversation/__tests__/useConversation.test.tsx

@@ -0,0 +1,243 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { act, cleanup, renderHook, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+
+// The focus-refetch tests broadcast window events, which reach EVERY
+// still-mounted hook in this file — including earlier tests' hooks whose
+// one-shot mock chains are exhausted. Unmount between tests so a window
+// broadcast only ever exercises the test that sent it.
+afterEach(cleanup);
+import { create } from "@bufbuild/protobuf";
+import { StigmerError } from "@stigmer/sdk";
+import {
+  ChannelConversationSchema,
+  ConversationControl,
+} from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+import { StigmerContext } from "../../context";
+import { FetchCacheContext } from "../../internal/FetchCacheProvider";
+import { useConversation } from "../useConversation";
+
+function row(overrides: { control?: ConversationControl; controlledBy?: string } = {}) {
+  return create(ChannelConversationSchema, {
+    agentChannelId: "ach_1",
+    conversationKey: "15550001111",
+    org: "acme",
+    control: overrides.control ?? ConversationControl.control_agent,
+    controlledBy: overrides.controlledBy ?? "",
+    displayName: "Pat",
+  });
+}
+
+function notFound() {
+  return new StigmerError("not-found", "no conversation with this key exists on channel ach_1", 5);
+}
+
+function createMockStigmer(getConversation: (input: unknown) => Promise<unknown>) {
+  return { agentChannel: { getConversation } } as never;
+}
+
+function wrapper(client: unknown) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <FetchCacheContext.Provider value={null}>
+        <StigmerContext.Provider value={client as never}>
+          {children}
+        </StigmerContext.Provider>
+      </FetchCacheContext.Provider>
+    );
+  };
+}
+
+const NO_POLL = { refetchIntervalMs: false as const };
+
+describe("useConversation", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("loads the conversation row", async () => {
+    const getConversation = vi.fn().mockResolvedValue(row());
+    const { result } = renderHook(
+      () => useConversation("ach_1", "15550001111", NO_POLL),
+      { wrapper: wrapper(createMockStigmer(getConversation)) },
+    );
+
+    expect(result.current.isLoading).toBe(true);
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.conversation?.displayName).toBe("Pat");
+    expect(result.current.awaitingCustomer).toBe(false);
+    expect(result.current.error).toBeNull();
+    expect(getConversation).toHaveBeenCalledWith(
+      expect.objectContaining({ agentChannelId: "ach_1", conversationKey: "15550001111" }),
+    );
+  });
+
+  it("answers NOT_FOUND as the awaiting-customer state, never an error", async () => {
+    const getConversation = vi.fn().mockRejectedValue(notFound());
+    const { result } = renderHook(
+      () => useConversation("ach_1", "15550001111", NO_POLL),
+      { wrapper: wrapper(createMockStigmer(getConversation)) },
+    );
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    // A cold-send conversation has a timeline before it has a row; the
+    // hook must let consumers render "controls unlock when the customer
+    // writes" rather than an error page.
+    expect(result.current.awaitingCustomer).toBe(true);
+    expect(result.current.conversation).toBeNull();
+    expect(result.current.error).toBeNull();
+  });
+
+  it("surfaces every other failure as the error state", async () => {
+    const getConversation = vi
+      .fn()
+      .mockRejectedValue(new StigmerError("permission-denied", "unauthorized", 7));
+    const { result } = renderHook(
+      () => useConversation("ach_1", "15550001111", NO_POLL),
+      { wrapper: wrapper(createMockStigmer(getConversation)) },
+    );
+
+    await waitFor(() => expect(result.current.error).not.toBeNull());
+    expect(result.current.awaitingCustomer).toBe(false);
+    expect(result.current.conversation).toBeNull();
+  });
+
+  it("skips fetching for empty identity (stable no-op)", async () => {
+    const getConversation = vi.fn();
+    const { result } = renderHook(() => useConversation("", "", NO_POLL), {
+      wrapper: wrapper(createMockStigmer(getConversation)),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(getConversation).not.toHaveBeenCalled();
+  });
+
+  it("fences a stale in-flight poll behind applyServerState — command truth is never overwritten", async () => {
+    // Sequence: the first read answers agent-held; a second read is
+    // started and parked in flight; a takeover response is applied; the
+    // parked read then resolves with the PRE-command state. The fence
+    // must discard it — otherwise the control banner flips back to
+    // "agent" under the cursor of the human who just took over, until
+    // the next poll corrects it.
+    let release: (value: unknown) => void = () => {};
+    const parked = new Promise((resolve) => {
+      release = resolve;
+    });
+    const getConversation = vi
+      .fn()
+      .mockResolvedValueOnce(row())
+      .mockReturnValueOnce(parked);
+
+    const { result } = renderHook(
+      () => useConversation("ach_1", "15550001111", NO_POLL),
+      { wrapper: wrapper(createMockStigmer(getConversation)) },
+    );
+    await waitFor(() =>
+      expect(result.current.conversation?.control).toBe(ConversationControl.control_agent),
+    );
+
+    act(() => result.current.refetch());
+    await waitFor(() => expect(result.current.isRefetching).toBe(true));
+
+    const taken = row({ control: ConversationControl.control_human, controlledBy: "idt_me" });
+    act(() => result.current.applyServerState(taken));
+    expect(result.current.conversation?.control).toBe(ConversationControl.control_human);
+
+    await act(async () => {
+      release(row());
+      await parked;
+    });
+
+    expect(result.current.conversation?.control).toBe(ConversationControl.control_human);
+    expect(result.current.conversation?.controlledBy).toBe("idt_me");
+    // The fenced answer still settles the in-flight flag, so polling
+    // can resume — a stranded flag would silence liveness forever.
+    await waitFor(() => expect(result.current.isRefetching).toBe(false));
+  });
+
+  it("resets state on identity change so channel A never renders under channel B", async () => {
+    const getConversation = vi
+      .fn()
+      .mockResolvedValueOnce(row())
+      .mockReturnValue(new Promise(() => {}));
+
+    const { result, rerender } = renderHook(
+      ({ key }: { key: string }) => useConversation("ach_1", key, NO_POLL),
+      {
+        wrapper: wrapper(createMockStigmer(getConversation)),
+        initialProps: { key: "15550001111" },
+      },
+    );
+    await waitFor(() => expect(result.current.conversation).not.toBeNull());
+
+    rerender({ key: "15550002222" });
+
+    expect(result.current.conversation).toBeNull();
+    expect(result.current.isLoading).toBe(true);
+  });
+
+  it("refetches the row when the window regains focus (DD-012: refocus is fresh)", async () => {
+    const getConversation = vi.fn().mockResolvedValue(row());
+    renderHook(() => useConversation("ach_1", "15550001111", NO_POLL), {
+      wrapper: wrapper(createMockStigmer(getConversation)),
+    });
+    await waitFor(() => expect(getConversation).toHaveBeenCalledTimes(1));
+
+    await act(async () => {
+      window.dispatchEvent(new Event("focus"));
+    });
+
+    await waitFor(() => expect(getConversation).toHaveBeenCalledTimes(2));
+  });
+
+  it("skips the focus refetch while a fetch is already in flight (no pile-up)", async () => {
+    let release: (value: unknown) => void = () => {};
+    const parked = new Promise((resolve) => {
+      release = resolve;
+    });
+    const getConversation = vi
+      .fn()
+      .mockResolvedValueOnce(row())
+      .mockReturnValueOnce(parked)
+      .mockResolvedValue(row());
+
+    const { result } = renderHook(
+      () => useConversation("ach_1", "15550001111", NO_POLL),
+      { wrapper: wrapper(createMockStigmer(getConversation)) },
+    );
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    // Park a fetch in flight, then refocus: the guard must not stack a
+    // second request on top of it.
+    act(() => result.current.refetch());
+    await waitFor(() => expect(result.current.isRefetching).toBe(true));
+
+    await act(async () => {
+      window.dispatchEvent(new Event("focus"));
+    });
+    expect(getConversation).toHaveBeenCalledTimes(2);
+
+    await act(async () => {
+      release(row());
+      await parked;
+    });
+    await waitFor(() => expect(result.current.isRefetching).toBe(false));
+  });
+
+  it("keeps the row reference stable across polls that change nothing (DD-010)", async () => {
+    const getConversation = vi.fn().mockImplementation(() => Promise.resolve(row()));
+    const { result } = renderHook(
+      () => useConversation("ach_1", "15550001111", NO_POLL),
+      { wrapper: wrapper(createMockStigmer(getConversation)) },
+    );
+    await waitFor(() => expect(result.current.conversation).not.toBeNull());
+    const first = result.current.conversation;
+
+    act(() => result.current.refetch());
+    await waitFor(() => expect(result.current.isRefetching).toBe(false));
+
+    expect(result.current.conversation).toBe(first);
+  });
+});