@stigmer/react 3.5.2 → 3.6.0

package/src/channel/__tests__/ChannelTemplatesDialog.test.tsx

@@ -0,0 +1,292 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, waitFor, cleanup, fireEvent } from "@testing-library/react";
+import type { ReactNode } from "react";
+import type { AgentChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
+import { AgentChannelInstallState } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/status_pb";
+import { StigmerContext } from "../../context";
+import { DeploymentModeContext } from "../../deployment-mode";
+import { FetchCacheContext } from "../../internal/FetchCacheProvider";
+import { ChannelTemplatesDialog } from "../ChannelTemplatesDialog";
+
+function makeChannel(overrides?: {
+  installState?: AgentChannelInstallState;
+  enabled?: boolean;
+  proactiveMessagingEnabled?: boolean;
+}): AgentChannel {
+  return {
+    metadata: { id: "ach_1", org: "acme", slug: "wa-main", name: "WA Main" },
+    spec: {
+      enabled: overrides?.enabled ?? true,
+      proactiveMessagingEnabled: overrides?.proactiveMessagingEnabled ?? true,
+      providerConfig: { case: "whatsapp", value: { phoneNumberId: "106" } },
+    },
+    status: {
+      installState:
+        overrides?.installState ?? AgentChannelInstallState.installed,
+      providerStatus: { case: undefined },
+    },
+  } as unknown as AgentChannel;
+}
+
+function makeTemplate(overrides?: Partial<Record<string, unknown>>) {
+  return {
+    name: "fee_reminder",
+    language: "en_US",
+    category: "UTILITY",
+    status: "APPROVED",
+    parameterFormat: "POSITIONAL",
+    parameterNames: ["1", "2"],
+    bodyText: "Hi {{1}}, your fee of {{2}} is due.",
+    headerFormat: "",
+    rejectionReason: "",
+    unsupportedReason: "",
+    ...overrides,
+  };
+}
+
+function renderDialog(
+  listTemplates: (input: unknown) => Promise<unknown>,
+  props?: {
+    channel?: AgentChannel;
+    onEditYaml?: () => void;
+    mode?: "cloud" | "local";
+  },
+) {
+  const client = { agentChannel: { listTemplates } } as never;
+  function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <FetchCacheContext.Provider value={null}>
+        <StigmerContext.Provider value={client}>
+          <DeploymentModeContext.Provider value={props?.mode ?? "cloud"}>
+            {children}
+          </DeploymentModeContext.Provider>
+        </StigmerContext.Provider>
+      </FetchCacheContext.Provider>
+    );
+  }
+  return render(
+    <ChannelTemplatesDialog
+      open
+      onOpenChange={vi.fn()}
+      channel={props?.channel ?? makeChannel()}
+      onEditYaml={props?.onEditYaml}
+      modal={false}
+    />,
+    { wrapper: Wrapper },
+  );
+}
+
+describe("ChannelTemplatesDialog", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    cleanup();
+  });
+
+  // -------------------------------------------------------------------------
+  // Readiness teaching states — no network call fires for any of them
+  // -------------------------------------------------------------------------
+
+  it("renders the cloud notice on a local deployment without fetching", () => {
+    const listTemplates = vi.fn();
+    renderDialog(listTemplates, { mode: "local" });
+
+    expect(
+      screen.getByText(/template registry can only be read on a cloud/),
+    ).toBeDefined();
+    expect(listTemplates).not.toHaveBeenCalled();
+  });
+
+  it("teaches connecting first for a pending install, with the provider's own sentence", () => {
+    const listTemplates = vi.fn();
+    renderDialog(listTemplates, {
+      channel: makeChannel({
+        installState: AgentChannelInstallState.pending_install,
+      }),
+    });
+
+    expect(screen.getByText("Connect this channel first")).toBeDefined();
+    // The card's describeChannel copy, reused verbatim.
+    expect(
+      screen.getByText(/WhatsApp connection hasn't been completed/),
+    ).toBeDefined();
+    expect(listTemplates).not.toHaveBeenCalled();
+  });
+
+  it("teaches the serving switch when the channel is off", () => {
+    const listTemplates = vi.fn();
+    renderDialog(listTemplates, {
+      channel: makeChannel({ enabled: false }),
+    });
+
+    expect(screen.getByText("This channel is turned off")).toBeDefined();
+    expect(listTemplates).not.toHaveBeenCalled();
+  });
+
+  it("teaches the proactive grant by its field name and routes to the YAML editor", () => {
+    const listTemplates = vi.fn();
+    const onEditYaml = vi.fn();
+    renderDialog(listTemplates, {
+      channel: makeChannel({ proactiveMessagingEnabled: false }),
+      onEditYaml,
+    });
+
+    expect(
+      screen.getByText("Business-initiated messaging is not enabled"),
+    ).toBeDefined();
+    // The description names the exact spec field — the only fix today.
+    expect(
+      screen.getByText(/proactive_messaging_enabled/),
+    ).toBeDefined();
+
+    fireEvent.click(
+      screen.getByRole("button", { name: "Edit channel YAML" }),
+    );
+    expect(onEditYaml).toHaveBeenCalledTimes(1);
+    expect(listTemplates).not.toHaveBeenCalled();
+  });
+
+  it("omits the YAML affordance when the host wires none", () => {
+    renderDialog(vi.fn(), {
+      channel: makeChannel({ proactiveMessagingEnabled: false }),
+    });
+
+    expect(
+      screen.queryByRole("button", { name: "Edit channel YAML" }),
+    ).toBeNull();
+  });
+
+  // -------------------------------------------------------------------------
+  // The fetched states
+  // -------------------------------------------------------------------------
+
+  it("fetches by the channel's own slug and org", async () => {
+    const listTemplates = vi.fn().mockResolvedValue({ entries: [] });
+    renderDialog(listTemplates);
+
+    await waitFor(() =>
+      expect(listTemplates).toHaveBeenCalledWith(
+        expect.objectContaining({ channel: "wa-main", org: "acme" }),
+      ),
+    );
+  });
+
+  it("relays a server refusal verbatim", async () => {
+    const listTemplates = vi
+      .fn()
+      .mockRejectedValue(
+        new Error(
+          "the channel provider's template registry is temporarily unreachable — try again shortly",
+        ),
+      );
+    renderDialog(listTemplates);
+
+    await waitFor(() =>
+      expect(
+        screen.getByText(/template registry is temporarily unreachable/),
+      ).toBeDefined(),
+    );
+  });
+
+  it('says "found" (never "you have none") when the registry answers empty, and links WhatsApp Manager', async () => {
+    const listTemplates = vi.fn().mockResolvedValue({ entries: [] });
+    renderDialog(listTemplates);
+
+    await waitFor(() =>
+      expect(
+        screen.getByText("No templates found for this channel"),
+      ).toBeDefined(),
+    );
+
+    const link = screen.getByRole("link", { name: /Open WhatsApp Manager/ });
+    expect(link.getAttribute("href")).toBe(
+      "https://business.facebook.com/wa/manage/message-templates/",
+    );
+    expect(link.getAttribute("target")).toBe("_blank");
+  });
+
+  it("renders the count header, identity, facts, and the verbatim status badge", async () => {
+    const listTemplates = vi.fn().mockResolvedValue({
+      entries: [
+        makeTemplate(),
+        makeTemplate({
+          name: "appeal_pending",
+          status: "IN_APPEAL",
+          category: "MARKETING",
+          headerFormat: "IMAGE",
+          bodyText: "Season offer!",
+        }),
+      ],
+    });
+    renderDialog(listTemplates);
+
+    await waitFor(() =>
+      expect(screen.getByText(/2 templates/)).toBeDefined(),
+    );
+    // Only the APPROVED one counts as sendable.
+    expect(screen.getByText(/1 ready to send/)).toBeDefined();
+
+    expect(screen.getByText("fee_reminder")).toBeDefined();
+    expect(screen.getAllByText("en_US")).toHaveLength(2);
+    expect(screen.getByText("UTILITY")).toBeDefined();
+    expect(screen.getByText("IMAGE header")).toBeDefined();
+    // Provider vocabulary verbatim — even statuses this build predates
+    // render as the provider's own word, never re-encoded.
+    expect(screen.getByText("APPROVED")).toBeDefined();
+    expect(screen.getByText("IN_APPEAL")).toBeDefined();
+  });
+
+  it("sets placeholders off from the literal body text", async () => {
+    const listTemplates = vi
+      .fn()
+      .mockResolvedValue({ entries: [makeTemplate()] });
+    const { container } = renderDialog(listTemplates);
+
+    await waitFor(() => expect(screen.getByText("fee_reminder")).toBeDefined());
+
+    const placeholders = [...container.querySelectorAll("code")].map(
+      (el) => el.textContent,
+    );
+    expect(placeholders).toEqual(["{{1}}", "{{2}}"]);
+  });
+
+  it("shows Stigmer's unsupported verdict on an approved-but-unsendable template", async () => {
+    const listTemplates = vi.fn().mockResolvedValue({
+      entries: [
+        makeTemplate({
+          name: "flow_template",
+          unsupportedReason:
+            "this template has a FLOW button, which this platform version cannot supply parameters for",
+        }),
+      ],
+    });
+    renderDialog(listTemplates);
+
+    await waitFor(() =>
+      expect(
+        screen.getByText(/Not sendable: this template has a FLOW button/),
+      ).toBeDefined(),
+    );
+    // Approved yet unsendable — the count must not claim it is ready.
+    expect(screen.getByText(/0 ready to send/)).toBeDefined();
+  });
+
+  it("shows the provider's rejection verdict verbatim", async () => {
+    const listTemplates = vi.fn().mockResolvedValue({
+      entries: [
+        makeTemplate({
+          name: "promo_blast",
+          status: "REJECTED",
+          rejectionReason: "PROMOTIONAL",
+        }),
+      ],
+    });
+    renderDialog(listTemplates);
+
+    await waitFor(() =>
+      expect(screen.getByText("Rejected: PROMOTIONAL")).toBeDefined(),
+    );
+  });
+});

package/src/channel/__tests__/providers.test.ts

@@ -38,6 +38,15 @@ describe("channel provider registry", () => {
     expect(channelProviderOf("telegram")).toBeNull();
     expect(channelProviderOf(undefined)).toBeNull();
   });
+
+  it("declares the template capability per provider — WhatsApp only", () => {
+    // Mirrors the server's proactive-sender registry (the de-facto
+    // provider filter behind listTemplates). Slack's false is not a
+    // gap: Slack has no template concept, so the Templates affordance
+    // hides rather than disables.
+    expect(channelProviderOf("whatsapp")?.supportsMessageTemplates).toBe(true);
+    expect(channelProviderOf("slack")?.supportsMessageTemplates).toBe(false);
+  });
 });
 
 describe("channel provider presentation", () => {

package/src/channel/__tests__/templatePresentation.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect } from "vitest";
+import {
+  splitTemplateBody,
+  templateStatusPhase,
+} from "../templatePresentation";
+
+describe("templateStatusPhase", () => {
+  // The documented five (DD-003) plus the observed extras (DD-005 D7:
+  // Meta's live vocabulary exceeds the documented set).
+  it.each([
+    ["APPROVED", "ready"],
+    ["PENDING", "pending"],
+    ["IN_APPEAL", "pending"],
+    ["PAUSED", "degraded"],
+    ["LIMIT_EXCEEDED", "degraded"],
+    ["REJECTED", "failed"],
+    ["DISABLED", "failed"],
+    ["PENDING_DELETION", "disabled"],
+    ["DELETED", "disabled"],
+  ] as const)("maps %s to %s", (status, phase) => {
+    expect(templateStatusPhase(status)).toBe(phase);
+  });
+
+  it("lands unknown statuses on draft — Meta can add states this build predates", () => {
+    expect(templateStatusPhase("SOME_FUTURE_STATE")).toBe("draft");
+    expect(templateStatusPhase("")).toBe("draft");
+  });
+
+  it("is case-sensitive like the wire — Meta emits uppercase, anything else is unknown", () => {
+    // The server relays Meta's verbatim uppercase strings; a lowercase
+    // variant is not a known status and must not color as one.
+    expect(templateStatusPhase("approved")).toBe("draft");
+  });
+});
+
+describe("splitTemplateBody", () => {
+  it("returns one text segment for a body without placeholders", () => {
+    expect(splitTemplateBody("Your class is confirmed.")).toEqual([
+      { kind: "text", value: "Your class is confirmed." },
+    ]);
+  });
+
+  it("splits positional placeholders out of surrounding text", () => {
+    expect(
+      splitTemplateBody("Hi {{1}}, your fee of {{2}} is due {{3}}."),
+    ).toEqual([
+      { kind: "text", value: "Hi " },
+      { kind: "placeholder", value: "{{1}}" },
+      { kind: "text", value: ", your fee of " },
+      { kind: "placeholder", value: "{{2}}" },
+      { kind: "text", value: " is due " },
+      { kind: "placeholder", value: "{{3}}" },
+      { kind: "text", value: "." },
+    ]);
+  });
+
+  it("recognizes named placeholders", () => {
+    expect(splitTemplateBody("Hello {{customer_name}}!")).toEqual([
+      { kind: "text", value: "Hello " },
+      { kind: "placeholder", value: "{{customer_name}}" },
+      { kind: "text", value: "!" },
+    ]);
+  });
+
+  it("handles adjacent placeholders and placeholder-only bodies", () => {
+    expect(splitTemplateBody("{{1}}{{2}}")).toEqual([
+      { kind: "placeholder", value: "{{1}}" },
+      { kind: "placeholder", value: "{{2}}" },
+    ]);
+  });
+
+  it("treats single or unbalanced braces as literal text", () => {
+    expect(splitTemplateBody("a {1} b {{unclosed")).toEqual([
+      { kind: "text", value: "a {1} b {{unclosed" },
+    ]);
+  });
+
+  it("returns no segments for an empty body", () => {
+    expect(splitTemplateBody("")).toEqual([]);
+  });
+
+  it("never rewrites — segments concatenate back to the input verbatim", () => {
+    const bodies = [
+      "Hi {{1}}, {{2}} due {{3}}.",
+      "  leading and trailing  ",
+      "{{ spaced }} stays verbatim",
+      "mixed {{name}} and {{1}}",
+    ];
+    for (const body of bodies) {
+      const joined = splitTemplateBody(body)
+        .map((s) => s.value)
+        .join("");
+      expect(joined).toBe(body);
+    }
+  });
+});

package/src/channel/__tests__/useChannelTemplateList.test.tsx

@@ -0,0 +1,216 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, waitFor, act } from "@testing-library/react";
+import type { ReactNode } from "react";
+import type { ListChannelTemplatesInput } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
+import { StigmerContext } from "../../context";
+import { FetchCacheContext } from "../../internal/FetchCacheProvider";
+import { useChannelTemplateList } from "../useChannelTemplateList";
+
+function createMockStigmer(overrides: {
+  listTemplates?: (input: ListChannelTemplatesInput) => Promise<unknown>;
+} = {}) {
+  return {
+    agentChannel: {
+      listTemplates:
+        overrides.listTemplates ?? vi.fn().mockResolvedValue({ entries: [] }),
+    },
+  } 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>
+    );
+  };
+}
+
+function makeTemplate(name: string, status: string) {
+  return {
+    name,
+    language: "en_US",
+    category: "UTILITY",
+    status,
+    parameterFormat: "POSITIONAL",
+    parameterNames: [],
+    bodyText: `Hi {{1}}, this is ${name}.`,
+    headerFormat: "",
+    rejectionReason: "",
+    unsupportedReason: "",
+  };
+}
+
+async function flush(): Promise<void> {
+  await act(async () => {
+    await Promise.resolve();
+  });
+}
+
+describe("useChannelTemplateList", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("loads templates by channel slug + org with the exact wire input", async () => {
+    const listTemplates = vi
+      .fn()
+      .mockResolvedValue({ entries: [makeTemplate("fee_reminder", "APPROVED")] });
+    const client = createMockStigmer({ listTemplates });
+
+    const { result } = renderHook(
+      () => useChannelTemplateList("wa-main", "acme"),
+      { wrapper: wrapper(client) },
+    );
+
+    expect(result.current.isLoading).toBe(true);
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.templates).toHaveLength(1);
+    expect(result.current.templates[0].name).toBe("fee_reminder");
+    expect(result.current.error).toBeNull();
+    // The RPC is keyed on slug + org, and the console's default leaves
+    // approvedOnly unset so every status renders with its badge.
+    expect(listTemplates).toHaveBeenCalledWith(
+      expect.objectContaining({
+        channel: "wa-main",
+        org: "acme",
+        approvedOnly: false,
+      }),
+    );
+  });
+
+  it("passes approvedOnly through when a caller sets it", async () => {
+    const listTemplates = vi.fn().mockResolvedValue({ entries: [] });
+    const client = createMockStigmer({ listTemplates });
+
+    renderHook(
+      () => useChannelTemplateList("wa-main", "acme", { approvedOnly: true }),
+      { wrapper: wrapper(client) },
+    );
+
+    await waitFor(() =>
+      expect(listTemplates).toHaveBeenCalledWith(
+        expect.objectContaining({ approvedOnly: true }),
+      ),
+    );
+  });
+
+  it("skips fetching when the channel slug is empty (stable no-op)", async () => {
+    const listTemplates = vi.fn();
+    const client = createMockStigmer({ listTemplates });
+
+    const { result } = renderHook(() => useChannelTemplateList("", "acme"), {
+      wrapper: wrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.templates).toEqual([]);
+    expect(listTemplates).not.toHaveBeenCalled();
+  });
+
+  it("skips fetching when the org is empty (stable no-op)", async () => {
+    const listTemplates = vi.fn();
+    const client = createMockStigmer({ listTemplates });
+
+    const { result } = renderHook(() => useChannelTemplateList("wa-main", ""), {
+      wrapper: wrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.templates).toEqual([]);
+    expect(listTemplates).not.toHaveBeenCalled();
+  });
+
+  it("surfaces the server's refusal verbatim", async () => {
+    const listTemplates = vi
+      .fn()
+      .mockRejectedValue(
+        new Error(
+          "unauthorized to use business messaging on this agent channel",
+        ),
+      );
+    const client = createMockStigmer({ listTemplates });
+
+    const { result } = renderHook(
+      () => useChannelTemplateList("wa-main", "acme"),
+      { wrapper: wrapper(client) },
+    );
+
+    await waitFor(() => expect(result.current.error).not.toBeNull());
+    expect(result.current.error?.message).toBe(
+      "unauthorized to use business messaging on this agent channel",
+    );
+    expect(result.current.templates).toEqual([]);
+  });
+
+  it("polls at 60s while a template is PENDING and stops once none are", async () => {
+    vi.useFakeTimers();
+
+    // First answer holds a PENDING entry; every later answer is settled.
+    let calls = 0;
+    const listTemplates = vi.fn(async () => {
+      calls += 1;
+      return {
+        entries:
+          calls === 1
+            ? [makeTemplate("fee_reminder", "PENDING")]
+            : [makeTemplate("fee_reminder", "APPROVED")],
+      };
+    });
+    const client = createMockStigmer({ listTemplates });
+
+    const { result } = renderHook(
+      () => useChannelTemplateList("wa-main", "acme"),
+      { wrapper: wrapper(client) },
+    );
+
+    await flush();
+    expect(listTemplates).toHaveBeenCalledTimes(1);
+    expect(result.current.templates[0].status).toBe("PENDING");
+
+    // The pending entry arms the poll; one interval later it re-reads.
+    act(() => {
+      vi.advanceTimersByTime(60_000);
+    });
+    await flush();
+    expect(listTemplates).toHaveBeenCalledTimes(2);
+    expect(result.current.templates[0].status).toBe("APPROVED");
+
+    // Settled data disarms the poll — no further reads, ever.
+    act(() => {
+      vi.advanceTimersByTime(300_000);
+    });
+    await flush();
+    expect(listTemplates).toHaveBeenCalledTimes(2);
+  });
+
+  it("never polls when the first answer is already settled", async () => {
+    vi.useFakeTimers();
+
+    const listTemplates = vi.fn(async () => ({
+      entries: [makeTemplate("fee_reminder", "APPROVED")],
+    }));
+    const client = createMockStigmer({ listTemplates });
+
+    renderHook(() => useChannelTemplateList("wa-main", "acme"), {
+      wrapper: wrapper(client),
+    });
+
+    await flush();
+    expect(listTemplates).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      vi.advanceTimersByTime(300_000);
+    });
+    await flush();
+    expect(listTemplates).toHaveBeenCalledTimes(1);
+  });
+});