@stigmer/react 3.12.4 → 3.12.5

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

@@ -40,10 +40,45 @@ describe("ConversationComposer", () => {
     const input = screen.getByLabelText("Reply to the customer");
     await user.type(input, "on my way{Enter}");
 
-    expect(onSend).toHaveBeenCalledWith("on my way");
+    // One reply command, two lanes (cloud#260): the textarea always
+    // submits the text lane of the payload union.
+    expect(onSend).toHaveBeenCalledWith({ kind: "text", body: "on my way" });
     await waitFor(() => expect((input as HTMLTextAreaElement).value).toBe(""));
   });
 
+  it("renders the template affordance only when a picker is wired, disabled while sending", () => {
+    const onOpenTemplatePicker = vi.fn();
+    const { rerender } = render(
+      <ConversationComposer onSend={vi.fn()} isSending={false} disabledReason={null} />,
+    );
+    expect(screen.queryByRole("button", { name: "Send a template reply" })).toBeNull();
+
+    rerender(
+      <ConversationComposer
+        onSend={vi.fn()}
+        isSending={false}
+        disabledReason={null}
+        onOpenTemplatePicker={onOpenTemplatePicker}
+      />,
+    );
+    const affordance = screen.getByRole("button", { name: "Send a template reply" });
+    affordance.click();
+    expect(onOpenTemplatePicker).toHaveBeenCalledTimes(1);
+
+    rerender(
+      <ConversationComposer
+        onSend={vi.fn()}
+        isSending={true}
+        disabledReason={null}
+        onOpenTemplatePicker={onOpenTemplatePicker}
+      />,
+    );
+    expect(
+      (screen.getByRole("button", { name: "Send a template reply" }) as HTMLButtonElement)
+        .disabled,
+    ).toBe(true);
+  });
+
   it("keeps the draft and shows the refusal detail verbatim when the send is refused", async () => {
     const user = userEvent.setup();
     const onSend = vi
@@ -118,6 +153,26 @@ describe("ConversationComposer", () => {
     expect(advisoryEl?.querySelector("button, a, [tabindex]")).toBeNull();
   });
 
+  it("keeps the advisory interaction-free even with a template picker wired (F-18)", () => {
+    render(
+      <ConversationComposer
+        onSend={vi.fn()}
+        isSending={false}
+        disabledReason={null}
+        advisory="The window has closed — send an approved template with the template button."
+        onOpenTemplatePicker={vi.fn()}
+      />,
+    );
+    const input = screen.getByLabelText("Reply to the customer");
+    const advisoryEl = document.getElementById(
+      input.getAttribute("aria-describedby") as string,
+    );
+    // The way forward lives on the persistent affordance BESIDE Send —
+    // the description itself must never grow a control.
+    expect(advisoryEl?.querySelector("button, a, [tabindex]")).toBeNull();
+    expect(screen.getByRole("button", { name: "Send a template reply" })).toBeDefined();
+  });
+
   it("renders no advisory and no dangling description when there is no claim", () => {
     render(
       <ConversationComposer onSend={vi.fn()} isSending={false} disabledReason={null} advisory={null} />,

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

@@ -0,0 +1,224 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import type { ReactNode } from "react";
+import { create } from "@bufbuild/protobuf";
+import {
+  ChannelSendOutcome,
+  SendChannelMessageOutputSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
+import { StigmerContext } from "../../context";
+import { FetchCacheContext } from "../../internal/FetchCacheProvider";
+import { ConversationTemplatePickerDialog } from "../ConversationTemplatePickerDialog";
+
+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 output(outcome: ChannelSendOutcome, detail = "") {
+  return create(SendChannelMessageOutputSchema, {
+    outcome,
+    outboundMessageId: outcome === ChannelSendOutcome.refused ? "" : "obm_1",
+    detail,
+  });
+}
+
+function renderPicker(options?: {
+  templates?: unknown[];
+  onSend?: ReturnType<typeof vi.fn>;
+  onOpenChange?: ReturnType<typeof vi.fn>;
+  isSending?: boolean;
+}) {
+  const listTemplates = vi
+    .fn()
+    .mockResolvedValue({ entries: options?.templates ?? [makeTemplate()] });
+  const onSend =
+    options?.onSend ?? vi.fn().mockResolvedValue(output(ChannelSendOutcome.accepted));
+  const client = { agentChannel: { listTemplates } } as never;
+  function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <FetchCacheContext.Provider value={null}>
+        <StigmerContext.Provider value={client}>{children}</StigmerContext.Provider>
+      </FetchCacheContext.Provider>
+    );
+  }
+  const view = render(
+    <ConversationTemplatePickerDialog
+      open
+      onOpenChange={options?.onOpenChange ?? vi.fn()}
+      channelSlug="wa-main"
+      org="acme"
+      onSend={onSend}
+      isSending={options?.isSending ?? false}
+      modal={false}
+    />,
+    { wrapper: Wrapper },
+  );
+  return { view, listTemplates, onSend };
+}
+
+describe("ConversationTemplatePickerDialog", () => {
+  afterEach(() => cleanup());
+
+  it("lists approved templates and asks the wire for approved only", async () => {
+    const { listTemplates } = renderPicker();
+
+    await waitFor(() => expect(screen.getByText("fee_reminder")).toBeDefined());
+    expect(listTemplates).toHaveBeenCalledWith(
+      expect.objectContaining({ channel: "wa-main", org: "acme", approvedOnly: true }),
+    );
+  });
+
+  it("marks unsupported and image-header templates unsendable, with the reason", async () => {
+    renderPicker({
+      templates: [
+        makeTemplate({
+          name: "flow_template",
+          unsupportedReason: "FLOW buttons are not supported",
+        }),
+        makeTemplate({ name: "hero_image", headerFormat: "IMAGE" }),
+        makeTemplate(),
+      ],
+    });
+
+    await waitFor(() => expect(screen.getByText("fee_reminder")).toBeDefined());
+    const unsupported = screen
+      .getByText("flow_template")
+      .closest("button") as HTMLButtonElement;
+    expect(unsupported.disabled).toBe(true);
+    expect(screen.getByText(/FLOW buttons are not supported/)).toBeDefined();
+
+    // The v1 scope cut (cloud#260): the send payload's image link has no
+    // console-side source yet, so the template shows but cannot be picked.
+    const imageHeader = screen
+      .getByText("hero_image")
+      .closest("button") as HTMLButtonElement;
+    expect(imageHeader.disabled).toBe(true);
+    expect(screen.getByText(/image header needs a hosted image/)).toBeDefined();
+
+    const sendable = screen
+      .getByText("fee_reminder")
+      .closest("button") as HTMLButtonElement;
+    expect(sendable.disabled).toBe(false);
+  });
+
+  it("phrases an empty registry answer as none FOUND, never none exist", async () => {
+    renderPicker({ templates: [] });
+    await waitFor(() =>
+      expect(screen.getByText("No approved templates found")).toBeDefined(),
+    );
+  });
+
+  it("fills variables with a live preview and only then enables Send", async () => {
+    const user = userEvent.setup();
+    renderPicker();
+
+    await waitFor(() => expect(screen.getByText("fee_reminder")).toBeDefined());
+    await user.click(screen.getByText("fee_reminder"));
+
+    const send = screen.getByRole("button", { name: "Send template" }) as HTMLButtonElement;
+    expect(send.disabled).toBe(true);
+
+    await user.type(screen.getByLabelText("1"), "Noor");
+    await user.type(screen.getByLabelText("2"), "$40");
+
+    // The preview substitutes the filled values into the verbatim body —
+    // the exact message the customer receives. Segments render as
+    // separate spans, so assert on the whole paragraph.
+    const preview = screen.getByText("Preview").nextElementSibling;
+    expect(preview?.textContent).toBe("Hi Noor, your fee of $40 is due.");
+    expect(send.disabled).toBe(false);
+  });
+
+  it("sends the chosen entry's name, language, and trimmed parameters, and closes on accepted", async () => {
+    const user = userEvent.setup();
+    const onOpenChange = vi.fn();
+    const { onSend } = renderPicker({ onOpenChange });
+
+    await waitFor(() => expect(screen.getByText("fee_reminder")).toBeDefined());
+    await user.click(screen.getByText("fee_reminder"));
+    await user.type(screen.getByLabelText("1"), " Noor ");
+    await user.type(screen.getByLabelText("2"), "$40");
+    await user.click(screen.getByRole("button", { name: "Send template" }));
+
+    await waitFor(() =>
+      expect(onSend).toHaveBeenCalledWith({
+        kind: "template",
+        name: "fee_reminder",
+        language: "en_US",
+        parameters: { "1": "Noor", "2": "$40" },
+      }),
+    );
+    await waitFor(() => expect(onOpenChange).toHaveBeenCalledWith(false));
+  });
+
+  it("keeps the dialog open with every value intact and shows the detail verbatim on refusal", async () => {
+    const user = userEvent.setup();
+    const onOpenChange = vi.fn();
+    const onSend = vi
+      .fn()
+      .mockResolvedValue(
+        output(ChannelSendOutcome.refused, "template 'fee_reminder' is PAUSED on WhatsApp"),
+      );
+    renderPicker({ onSend, onOpenChange });
+
+    await waitFor(() => expect(screen.getByText("fee_reminder")).toBeDefined());
+    await user.click(screen.getByText("fee_reminder"));
+    await user.type(screen.getByLabelText("1"), "Noor");
+    await user.type(screen.getByLabelText("2"), "$40");
+    await user.click(screen.getByRole("button", { name: "Send template" }));
+
+    await waitFor(() =>
+      expect(
+        screen.getByText("template 'fee_reminder' is PAUSED on WhatsApp"),
+      ).toBeDefined(),
+    );
+    // The words never left; the correction the detail asks for starts
+    // from the values already filled (the composer's draft contract).
+    expect(onOpenChange).not.toHaveBeenCalledWith(false);
+    expect((screen.getByLabelText("1") as HTMLInputElement).value).toBe("Noor");
+    expect((screen.getByLabelText("2") as HTMLInputElement).value).toBe("$40");
+  });
+
+  it("keeps the dialog open and renders a thrown failure", async () => {
+    const user = userEvent.setup();
+    const onSend = vi.fn().mockRejectedValue(new Error("transport exploded"));
+    renderPicker({ onSend });
+
+    await waitFor(() => expect(screen.getByText("fee_reminder")).toBeDefined());
+    await user.click(screen.getByText("fee_reminder"));
+    await user.type(screen.getByLabelText("1"), "Noor");
+    await user.type(screen.getByLabelText("2"), "$40");
+    await user.click(screen.getByRole("button", { name: "Send template" }));
+
+    await waitFor(() => expect(screen.getByText(/transport exploded/)).toBeDefined());
+    expect((screen.getByLabelText("1") as HTMLInputElement).value).toBe("Noor");
+  });
+
+  it("navigates back to the list, discarding the selection", async () => {
+    const user = userEvent.setup();
+    renderPicker({
+      templates: [makeTemplate(), makeTemplate({ name: "order_update" })],
+    });
+
+    await waitFor(() => expect(screen.getByText("fee_reminder")).toBeDefined());
+    await user.click(screen.getByText("fee_reminder"));
+    expect(screen.getByRole("button", { name: "Send template" })).toBeDefined();
+
+    await user.click(screen.getByRole("button", { name: "Back to the template list" }));
+    expect(screen.getByText("order_update")).toBeDefined();
+    expect(screen.queryByRole("button", { name: "Send template" })).toBeNull();
+  });
+});

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

@@ -100,7 +100,9 @@ describe("useConversationParticipation", () => {
       { wrapper: wrapper(client) },
     );
 
-    const output = await act(() => result.current.reply("on my way"));
+    const output = await act(() =>
+      result.current.reply({ kind: "text", body: "on my way" }),
+    );
 
     expect(output.outboundMessageId).toBe("obm_1");
     const agentChannel = (client as { agentChannel: Record<string, ReturnType<typeof vi.fn>> })
@@ -109,7 +111,10 @@ describe("useConversationParticipation", () => {
       expect.objectContaining({
         ...IDENTITY,
         payload: expect.objectContaining({
-          kind: expect.objectContaining({ case: "text" }),
+          kind: expect.objectContaining({
+            case: "text",
+            value: expect.objectContaining({ body: "on my way" }),
+          }),
         }),
       }),
     );
@@ -121,6 +126,40 @@ describe("useConversationParticipation", () => {
     );
   });
 
+  it("reply sends the template lane through the same command — name, language, and parameters verbatim", async () => {
+    const client = createMockStigmer();
+    const { result } = renderHook(() => useConversationParticipation(IDENTITY), {
+      wrapper: wrapper(client),
+    });
+
+    await act(() =>
+      result.current.reply({
+        kind: "template",
+        name: "order_update",
+        language: "en_US",
+        parameters: { "1": "Noor", "2": "tomorrow" },
+      }),
+    );
+
+    const agentChannel = (client as { agentChannel: Record<string, ReturnType<typeof vi.fn>> })
+      .agentChannel;
+    expect(agentChannel.reply).toHaveBeenCalledWith(
+      expect.objectContaining({
+        ...IDENTITY,
+        payload: expect.objectContaining({
+          kind: expect.objectContaining({
+            case: "template",
+            value: expect.objectContaining({
+              name: "order_update",
+              language: "en_US",
+              parameters: { "1": "Noor", "2": "tomorrow" },
+            }),
+          }),
+        }),
+      }),
+    );
+  });
+
   it("still resolves the reply when the follow-up row read fails — the send outcome is the answer", async () => {
     const client = createMockStigmer({
       getConversation: vi.fn().mockRejectedValue(new Error("blip")),
@@ -131,7 +170,9 @@ describe("useConversationParticipation", () => {
       { wrapper: wrapper(client) },
     );
 
-    const output = await act(() => result.current.reply("on my way"));
+    const output = await act(() =>
+      result.current.reply({ kind: "text", body: "on my way" }),
+    );
 
     expect(output.outboundMessageId).toBe("obm_1");
     expect(onConversation).not.toHaveBeenCalled();
@@ -144,7 +185,7 @@ describe("useConversationParticipation", () => {
       wrapper: wrapper(client),
     });
 
-    await act(() => result.current.reply("on my way"));
+    await act(() => result.current.reply({ kind: "text", body: "on my way" }));
 
     const agentChannel = (client as { agentChannel: Record<string, ReturnType<typeof vi.fn>> })
       .agentChannel;

package/src/conversation/index.ts

@@ -22,6 +22,9 @@ export type { ConversationAttentionBannerProps } from "./ConversationAttentionBa
 export { ConversationComposer } from "./ConversationComposer.js";
 export type { ConversationComposerProps } from "./ConversationComposer.js";
 
+export { ConversationTemplatePickerDialog } from "./ConversationTemplatePickerDialog.js";
+export type { ConversationTemplatePickerDialogProps } from "./ConversationTemplatePickerDialog.js";
+
 export { useConversation } from "./useConversation.js";
 export type {
   UseConversationOptions,
@@ -49,6 +52,7 @@ export type {
 export { useConversationParticipation } from "./useConversationParticipation.js";
 export type {
   ConversationCommand,
+  ConversationReplyPayload,
   UseConversationParticipationOptions,
   UseConversationParticipationReturn,
 } from "./useConversationParticipation.js";

package/src/conversation/useConversationParticipation.ts

@@ -17,6 +17,43 @@ import { useKeyedSubmission } from "../internal/useKeyedSubmission.js";
 /** The four staff-facing participation commands. */
 export type ConversationCommand = "reply" | "takeOver" | "handBack" | "clearAttention";
 
+/**
+ * A staff reply's payload — the client-side face of the wire's
+ * `ChannelOutboundPayload` oneof. Reply is ONE command with two lanes,
+ * never two commands: both lanes share the implicit takeover, the
+ * `"reply"` pending key, and the outcome contract.
+ *
+ * - `text` — free-form; requires an open 24-hour customer-service
+ *   window on providers that enforce one (WhatsApp).
+ * - `template` — a provider-approved message template, the only lane
+ *   for a closed window. `language` is always required here (the wire
+ *   allows omitting it for single-language names, but a caller that
+ *   picked a template knows its language — sending it structurally
+ *   avoids the ambiguity refusal). Image-header templates are not yet
+ *   sendable from the SDK: the wire's `header_image_link` needs a
+ *   public HTTPS asset no console surface can supply today.
+ */
+export type ConversationReplyPayload =
+  | {
+      readonly kind: "text";
+      /** The message body, as the customer will receive it. */
+      readonly body: string;
+    }
+  | {
+      readonly kind: "template";
+      /** Template name on the channel provider's registry. */
+      readonly name: string;
+      /** Template language code (e.g. `"en"`, `"en_US"`). */
+      readonly language: string;
+      /**
+       * Variable values: keyed by parameter name for NAMED templates,
+       * by position (`"1"`, `"2"`, …) for POSITIONAL ones — exactly the
+       * template's declared parameters, no more, no fewer (the server's
+       * pre-check refuses mismatches with a corrective detail).
+       */
+      readonly parameters: Readonly<Record<string, string>>;
+    };
+
 /** Options for {@link useConversationParticipation}. */
 export interface UseConversationParticipationOptions {
   /** AgentChannel the conversation belongs to. */
@@ -37,13 +74,16 @@ export interface UseConversationParticipationOptions {
 /** Return value of {@link useConversationParticipation}. */
 export interface UseConversationParticipationReturn {
   /**
-   * Send a staff text reply. Resolves with the truthful outcome of the
-   * inline attempt: `accepted` (with `outboundMessageId` — the item will
-   * appear on the timeline as `ob:<that id>`), `queued`, or `refused`.
+   * Send a staff reply — text or template (see
+   * {@link ConversationReplyPayload}). Resolves with the truthful
+   * outcome of the inline attempt: `accepted` (with
+   * `outboundMessageId` — the item will appear on the timeline as
+   * `ob:<that id>`), `queued`, or `refused` (template pre-check
+   * refusals land here too, with the server's corrective detail).
    * A `refused` outcome WITHOUT an `outboundMessageId` left no ledger
    * row and no timeline item will ever exist for it.
    */
-  readonly reply: (text: string) => Promise<SendChannelMessageOutput>;
+  readonly reply: (payload: ConversationReplyPayload) => Promise<SendChannelMessageOutput>;
   /**
    * Take the conversation over: the agent goes quiet until handBack.
    * Resolves with the fresh row — for the LOSER of a concurrent
@@ -120,13 +160,25 @@ export function useConversationParticipation(
   );
 
   const reply = useCallback(
-    (text: string) =>
+    (payload: ConversationReplyPayload) =>
       run("reply", async () => {
         const output = await stigmer.agentChannel.reply(
           create(ReplyToConversationInputSchema, {
             agentChannelId,
             conversationKey,
-            payload: { kind: { case: "text", value: { body: text } } },
+            payload: {
+              kind:
+                payload.kind === "text"
+                  ? { case: "text", value: { body: payload.body } }
+                  : {
+                      case: "template",
+                      value: {
+                        name: payload.name,
+                        language: payload.language,
+                        parameters: { ...payload.parameters },
+                      },
+                    },
+            },
           }),
         );
         // The implicit takeover flipped control BEFORE the send ran —