@stigmer/react 3.1.16 → 3.2.0

package/src/channel-app/__tests__/channelAppWhatsApp.test.tsx

@@ -0,0 +1,270 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, screen, fireEvent, waitFor, cleanup } from "@testing-library/react";
+import type { ReactNode } from "react";
+import type { ChannelAppInput } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { CreateChannelAppForm, type ChannelAppCreateHandoff } from "../CreateChannelAppForm";
+import { ChannelAppDetailPanel } from "../ChannelAppDetailPanel";
+
+afterEach(cleanup);
+
+function createMockStigmer(overrides: {
+  create?: (input: ChannelAppInput) => Promise<unknown>;
+  update?: (input: ChannelAppInput) => Promise<unknown>;
+} = {}) {
+  return {
+    baseUrl: "https://api.stigmer.ai",
+    channelapp: {
+      create: overrides.create ?? vi.fn().mockResolvedValue({
+        metadata: { id: "chapp_new", org: "acme", slug: "acme-whatsapp" },
+      }),
+      update: overrides.update ?? vi.fn().mockResolvedValue({}),
+      delete: vi.fn().mockResolvedValue({}),
+    },
+  } as never;
+}
+
+function Providers({ client, children }: { client: unknown; children: ReactNode }) {
+  return (
+    <StigmerContext.Provider value={client as never}>
+      {children}
+    </StigmerContext.Provider>
+  );
+}
+
+/** A WhatsApp channel app as the server returns it — secrets redacted. */
+function makeWhatsAppApp() {
+  return {
+    metadata: { id: "chapp_1", org: "acme", slug: "acme-whatsapp", name: "Acme WhatsApp" },
+    spec: {
+      providerConfig: {
+        case: "whatsapp",
+        value: {
+          appId: "1234567890123456",
+          appSecret: "***REDACTED***",
+          accessToken: "***REDACTED***",
+          verifyToken: "***REDACTED***",
+        },
+      },
+    },
+  } as never;
+}
+
+describe("CreateChannelAppForm — WhatsApp branch", () => {
+  it("switches the credential fields when the provider changes", async () => {
+    render(
+      <Providers client={createMockStigmer()}>
+        <CreateChannelAppForm org="acme" />
+      </Providers>,
+    );
+
+    // Slack is the default: manifest + OAuth credentials.
+    expect(screen.getByText(/slack app manifest/i)).toBeTruthy();
+    expect(screen.getByLabelText(/client id/i)).toBeTruthy();
+
+    fireEvent.click(screen.getByRole("radio", { name: /whatsapp/i }));
+
+    // WhatsApp: Meta credentials, no manifest (Meta has no equivalent).
+    expect(screen.queryByText(/slack app manifest/i)).toBeNull();
+    expect(screen.getByLabelText(/app id/i)).toBeTruthy();
+    expect(screen.getByLabelText(/app secret/i)).toBeTruthy();
+    expect(screen.getByLabelText(/access token/i)).toBeTruthy();
+    expect(screen.getByLabelText(/verify token/i)).toBeTruthy();
+  });
+
+  it("pre-generates a strong verify token the user can override", () => {
+    render(
+      <Providers client={createMockStigmer()}>
+        <CreateChannelAppForm org="acme" />
+      </Providers>,
+    );
+
+    fireEvent.click(screen.getByRole("radio", { name: /whatsapp/i }));
+
+    // Generated, not empty: the token is customer-authored (DD-WA-3) but
+    // a strong default prevents guessable handshake secrets.
+    const tokenInput = screen.getByLabelText(/verify token/i) as HTMLInputElement;
+    expect(tokenInput.value).toMatch(/^[0-9a-f]{64}$/);
+
+    fireEvent.change(tokenInput, { target: { value: "my-own-token" } });
+    expect(tokenInput.value).toBe("my-own-token");
+  });
+
+  it("submits the whatsapp arm and hands the verify token to the host", async () => {
+    const create = vi.fn().mockResolvedValue({
+      metadata: { id: "chapp_new", org: "acme" },
+    });
+    const onCreated =
+      vi.fn<(app: unknown, handoff: ChannelAppCreateHandoff) => void>();
+
+    render(
+      <Providers client={createMockStigmer({ create })}>
+        <CreateChannelAppForm org="acme" onCreated={onCreated} />
+      </Providers>,
+    );
+
+    fireEvent.click(screen.getByRole("radio", { name: /whatsapp/i }));
+    fireEvent.change(screen.getByLabelText(/^name$/i), {
+      target: { value: "Acme WhatsApp" },
+    });
+    fireEvent.change(screen.getByLabelText(/app id/i), {
+      target: { value: "1234567890123456" },
+    });
+    fireEvent.change(screen.getByLabelText(/app secret/i), {
+      target: { value: "shhh-secret" },
+    });
+    fireEvent.change(screen.getByLabelText(/access token/i), {
+      target: { value: "EAAG-token" },
+    });
+    fireEvent.change(screen.getByLabelText(/verify token/i), {
+      target: { value: "verify-me" },
+    });
+    fireEvent.click(
+      screen.getByRole("button", { name: /register channel app/i }),
+    );
+
+    await waitFor(() => expect(create).toHaveBeenCalled());
+    expect(create).toHaveBeenCalledWith({
+      name: "Acme WhatsApp",
+      org: "acme",
+      whatsapp: {
+        appId: "1234567890123456",
+        appSecret: "shhh-secret",
+        accessToken: "EAAG-token",
+        verifyToken: "verify-me",
+      },
+    });
+
+    // The handoff carries the once-visible token: the detail panel shows
+    // it alongside the freshly-minted webhook URL (it answers redacted
+    // from now on).
+    await waitFor(() => expect(onCreated).toHaveBeenCalled());
+    expect(onCreated.mock.calls[0][1]).toEqual({ verifyToken: "verify-me" });
+  });
+
+  it("hands off no secrets for Slack apps", async () => {
+    const create = vi.fn().mockResolvedValue({
+      metadata: { id: "chapp_new", org: "acme" },
+    });
+    const onCreated =
+      vi.fn<(app: unknown, handoff: ChannelAppCreateHandoff) => void>();
+
+    render(
+      <Providers client={createMockStigmer({ create })}>
+        <CreateChannelAppForm org="acme" onCreated={onCreated} />
+      </Providers>,
+    );
+
+    fireEvent.change(screen.getByLabelText(/^name$/i), {
+      target: { value: "Acme Bot" },
+    });
+    fireEvent.change(screen.getByLabelText(/client id/i), {
+      target: { value: "123.456" },
+    });
+    fireEvent.change(screen.getByLabelText(/client secret/i), {
+      target: { value: "cs" },
+    });
+    fireEvent.change(screen.getByLabelText(/signing secret/i), {
+      target: { value: "ss" },
+    });
+    fireEvent.click(
+      screen.getByRole("button", { name: /register channel app/i }),
+    );
+
+    await waitFor(() => expect(onCreated).toHaveBeenCalled());
+    expect(onCreated.mock.calls[0][1]).toEqual({});
+  });
+});
+
+describe("ChannelAppDetailPanel — WhatsApp branch", () => {
+  it("shows the callback URL and the handed-off verify token together, once", () => {
+    render(
+      <Providers client={createMockStigmer()}>
+        <ChannelAppDetailPanel
+          channelApp={makeWhatsAppApp()}
+          createHandoff={{ verifyToken: "verify-me" }}
+        />
+      </Providers>,
+    );
+
+    // Phase two of the setup needs both values in one place: the URL is
+    // minted at creation, the token was just entered and never answers
+    // in cleartext again.
+    expect(screen.getByText(/finish setup in meta/i)).toBeTruthy();
+    expect(
+      screen.getByText("https://api.stigmer.ai/webhook/whatsapp/chapp_1"),
+    ).toBeTruthy();
+    expect(screen.getByText("verify-me")).toBeTruthy();
+    // The subscribed field is named so the checklist is complete.
+    expect(screen.getByText(/messages/)).toBeTruthy();
+  });
+
+  it("explains the token's one-time visibility when there is no handoff", () => {
+    render(
+      <Providers client={createMockStigmer()}>
+        <ChannelAppDetailPanel channelApp={makeWhatsAppApp()} />
+      </Providers>,
+    );
+
+    expect(screen.getByText(/shown once at registration/i)).toBeTruthy();
+    expect(screen.queryByText("verify-me")).toBeNull();
+  });
+
+  it("rotates credentials through the whatsapp arm, preserving untouched secrets", async () => {
+    const update = vi.fn().mockResolvedValue({});
+
+    render(
+      <Providers client={createMockStigmer({ update })}>
+        <ChannelAppDetailPanel channelApp={makeWhatsAppApp()} />
+      </Providers>,
+    );
+
+    // Rotate one secret; the others keep the redaction marker, which the
+    // server treats as "keep the stored value".
+    fireEvent.change(screen.getByLabelText(/access token/i), {
+      target: { value: "EAAG-new-token" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: /save credentials/i }));
+
+    await waitFor(() => expect(update).toHaveBeenCalled());
+    expect(update).toHaveBeenCalledWith({
+      name: "Acme WhatsApp",
+      org: "acme",
+      slug: "acme-whatsapp",
+      whatsapp: {
+        appId: "1234567890123456",
+        appSecret: "***REDACTED***",
+        accessToken: "EAAG-new-token",
+        verifyToken: "***REDACTED***",
+      },
+    });
+  });
+
+  it("keeps the Slack detail body for Slack apps", () => {
+    const slackApp = {
+      metadata: { id: "chapp_s", org: "acme", slug: "acme-bot", name: "Acme Bot" },
+      spec: {
+        providerConfig: {
+          case: "slack",
+          value: {
+            clientId: "123.456",
+            clientSecret: "***REDACTED***",
+            signingSecret: "***REDACTED***",
+          },
+        },
+      },
+    } as never;
+
+    render(
+      <Providers client={createMockStigmer()}>
+        <ChannelAppDetailPanel channelApp={slackApp} />
+      </Providers>,
+    );
+
+    expect(screen.getByText(/finish setup in slack/i)).toBeTruthy();
+    expect(
+      screen.getByText("https://api.stigmer.ai/webhook/slack/chapp_s"),
+    ).toBeTruthy();
+    expect(screen.queryByText(/finish setup in meta/i)).toBeNull();
+  });
+});

package/src/channel-app/__tests__/slackAppSetup.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from "vitest";
+import {
+  buildSlackChannelAppManifest,
+  slackChannelAppRedirectUrl,
+  slackChannelAppWebhookUrl,
+  SLACK_CHANNEL_APP_BOT_EVENTS,
+  SLACK_CHANNEL_APP_BOT_SCOPES,
+} from "../slackAppSetup";
+
+describe("slackChannelAppWebhookUrl", () => {
+  it("builds the per-app events route — the path is the signing-secret discriminator", () => {
+    expect(slackChannelAppWebhookUrl("https://api.stigmer.ai", "chapp_01abc")).toBe(
+      "https://api.stigmer.ai/webhook/slack/chapp_01abc",
+    );
+  });
+
+  it("tolerates a trailing slash on the base URL", () => {
+    expect(slackChannelAppWebhookUrl("https://api.stigmer.ai/", "chapp_01abc")).toBe(
+      "https://api.stigmer.ai/webhook/slack/chapp_01abc",
+    );
+  });
+});
+
+describe("slackChannelAppRedirectUrl", () => {
+  it("derives the console callback route from an explicit origin", () => {
+    expect(slackChannelAppRedirectUrl("https://app.stigmer.ai")).toBe(
+      "https://app.stigmer.ai/oauth/slack/callback",
+    );
+  });
+});
+
+describe("buildSlackChannelAppManifest", () => {
+  it("renders the customer identity with the platform app's exact scope and event sets", () => {
+    const manifest = buildSlackChannelAppManifest({
+      name: "Acme Support Bot",
+      redirectUrl: "https://app.stigmer.ai/oauth/slack/callback",
+      webhookUrl: "https://api.stigmer.ai/webhook/slack/chapp_01abc",
+    });
+
+    expect(manifest).toContain("name: Acme Support Bot");
+    expect(manifest).toContain("display_name: Acme Support Bot");
+    expect(manifest).toContain(
+      '- "https://app.stigmer.ai/oauth/slack/callback"',
+    );
+    expect(manifest).toContain(
+      'request_url: "https://api.stigmer.ai/webhook/slack/chapp_01abc"',
+    );
+    for (const scope of SLACK_CHANNEL_APP_BOT_SCOPES) {
+      expect(manifest).toContain(`- ${scope}`);
+    }
+    for (const event of SLACK_CHANNEL_APP_BOT_EVENTS) {
+      expect(manifest).toContain(`- ${event}`);
+    }
+    // Deliberate platform mirrors that must never drift silently.
+    expect(manifest).toContain("org_deploy_enabled: false");
+    expect(manifest).toContain("socket_mode_enabled: false");
+  });
+
+  it("omits event subscriptions before the webhook URL exists (phase-one manifest)", () => {
+    const manifest = buildSlackChannelAppManifest({
+      name: "Acme Support Bot",
+      redirectUrl: "https://app.stigmer.ai/oauth/slack/callback",
+    });
+
+    expect(manifest).not.toContain("event_subscriptions");
+    expect(manifest).not.toContain("request_url");
+    // The rest of the manifest is intact.
+    expect(manifest).toContain("oauth_config:");
+    expect(manifest).toContain("org_deploy_enabled: false");
+  });
+
+  it("keeps the scope set at exactly four — scope minimalism is load-bearing", () => {
+    expect(SLACK_CHANNEL_APP_BOT_SCOPES).toHaveLength(4);
+  });
+});

package/src/channel-app/__tests__/useChannelAppHooks.test.tsx

@@ -0,0 +1,157 @@
+import { describe, it, expect, vi } from "vitest";
+import { renderHook, act, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import type { ChannelAppInput } from "@stigmer/sdk";
+import { StigmerContext } from "../../context";
+import { useChannelAppList } from "../useChannelAppList";
+import { useCreateChannelApp } from "../useCreateChannelApp";
+import { useUpdateChannelApp } from "../useUpdateChannelApp";
+import { useDeleteChannelApp } from "../useDeleteChannelApp";
+
+function createMockStigmer(channelapp: Record<string, unknown>) {
+  return { channelapp } as never;
+}
+
+function wrapper(client: unknown) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <StigmerContext.Provider value={client as never}>
+        {children}
+      </StigmerContext.Provider>
+    );
+  };
+}
+
+const APP = {
+  metadata: { id: "chapp_1", name: "Acme Support Bot", org: "acme", slug: "acme-support-bot" },
+  spec: {
+    providerConfig: {
+      case: "slack",
+      value: { clientId: "1234.5678", clientSecret: "***REDACTED***", signingSecret: "***REDACTED***" },
+    },
+  },
+};
+
+describe("useChannelAppList", () => {
+  it("fetches the org's channel apps", async () => {
+    const listByOrg = vi.fn().mockResolvedValue({ entries: [APP] });
+    const client = createMockStigmer({ listByOrg });
+
+    const { result } = renderHook(() => useChannelAppList("acme"), {
+      wrapper: wrapper(client),
+    });
+
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+    expect(result.current.channelApps).toHaveLength(1);
+    expect(listByOrg).toHaveBeenCalledWith(
+      expect.objectContaining({ org: "acme" }),
+    );
+  });
+
+  it("skips fetching while org is null (unresolved org)", () => {
+    const listByOrg = vi.fn();
+    const client = createMockStigmer({ listByOrg });
+
+    const { result } = renderHook(() => useChannelAppList(null), {
+      wrapper: wrapper(client),
+    });
+
+    expect(listByOrg).not.toHaveBeenCalled();
+    expect(result.current.channelApps).toEqual([]);
+  });
+});
+
+describe("useCreateChannelApp", () => {
+  it("creates and returns the server resource", async () => {
+    const create = vi.fn().mockResolvedValue(APP);
+    const client = createMockStigmer({ create });
+
+    const { result } = renderHook(() => useCreateChannelApp(), {
+      wrapper: wrapper(client),
+    });
+
+    const input: ChannelAppInput = {
+      name: "Acme Support Bot",
+      org: "acme",
+      slack: { clientId: "1234.5678", clientSecret: "s", signingSecret: "s2" },
+    };
+
+    await act(async () => {
+      await result.current.create(input);
+    });
+
+    expect(create).toHaveBeenCalledWith(input);
+    expect(result.current.error).toBeNull();
+  });
+
+  it("captures and rethrows failures", async () => {
+    const create = vi.fn().mockRejectedValue(new Error("unauthorized to create channel app in this organization"));
+    const client = createMockStigmer({ create });
+
+    const { result } = renderHook(() => useCreateChannelApp(), {
+      wrapper: wrapper(client),
+    });
+
+    await act(async () => {
+      await expect(
+        result.current.create({ name: "x", org: "acme" }),
+      ).rejects.toThrow("unauthorized");
+    });
+    expect(result.current.error?.message).toContain("unauthorized");
+  });
+});
+
+describe("useUpdateChannelApp", () => {
+  it("passes redaction markers through untouched — the keep-stored-value contract", async () => {
+    const update = vi.fn().mockResolvedValue(APP);
+    const client = createMockStigmer({ update });
+
+    const { result } = renderHook(() => useUpdateChannelApp(), {
+      wrapper: wrapper(client),
+    });
+
+    await act(async () => {
+      await result.current.update({
+        name: "Acme Support Bot",
+        org: "acme",
+        slack: {
+          clientId: "1234.5678",
+          clientSecret: "***REDACTED***",
+          signingSecret: "rotated",
+        },
+      });
+    });
+
+    expect(update).toHaveBeenCalledWith(
+      expect.objectContaining({
+        slack: expect.objectContaining({
+          clientSecret: "***REDACTED***",
+          signingSecret: "rotated",
+        }),
+      }),
+    );
+  });
+});
+
+describe("useDeleteChannelApp", () => {
+  it("deletes by id and surfaces the referencing-channels refusal", async () => {
+    const del = vi.fn().mockRejectedValue(
+      new Error("Cannot delete channel app: 1 agent channel(s) still reference it via spec.app_ref."),
+    );
+    const client = createMockStigmer({ delete: del });
+
+    const { result } = renderHook(() => useDeleteChannelApp(), {
+      wrapper: wrapper(client),
+    });
+
+    await act(async () => {
+      await expect(result.current.deleteApp("chapp_1")).rejects.toThrow(
+        "still reference it",
+      );
+    });
+
+    expect(del).toHaveBeenCalledWith({ resourceId: "chapp_1" });
+    expect(result.current.error?.message).toContain("still reference it");
+    expect(result.current.isDeleting).toBe(false);
+  });
+});

package/src/channel-app/__tests__/whatsappAppSetup.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from "vitest";
+import {
+  generateWhatsAppVerifyToken,
+  whatsappChannelAppWebhookUrl,
+  WHATSAPP_CHANNEL_APP_WEBHOOK_FIELDS,
+} from "../whatsappAppSetup";
+
+describe("whatsappChannelAppWebhookUrl", () => {
+  it("builds the per-app webhook path — the receiver's attribution key", () => {
+    expect(
+      whatsappChannelAppWebhookUrl("https://api.stigmer.ai", "chapp_123"),
+    ).toBe("https://api.stigmer.ai/webhook/whatsapp/chapp_123");
+  });
+
+  it("tolerates trailing slashes on the API origin", () => {
+    expect(
+      whatsappChannelAppWebhookUrl("https://api.stigmer.ai///", "chapp_123"),
+    ).toBe("https://api.stigmer.ai/webhook/whatsapp/chapp_123");
+  });
+});
+
+describe("generateWhatsAppVerifyToken", () => {
+  it("produces 32 bytes of entropy as paste-safe lowercase hex", () => {
+    const token = generateWhatsAppVerifyToken();
+    expect(token).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it("never repeats", () => {
+    expect(generateWhatsAppVerifyToken()).not.toBe(
+      generateWhatsAppVerifyToken(),
+    );
+  });
+});
+
+describe("WHATSAPP_CHANNEL_APP_WEBHOOK_FIELDS", () => {
+  it("subscribes to inbound messages only — deliberate field minimalism", () => {
+    expect(WHATSAPP_CHANNEL_APP_WEBHOOK_FIELDS).toEqual(["messages"]);
+  });
+});

package/src/channel-app/index.ts

@@ -0,0 +1,30 @@
+export { useChannelAppList } from "./useChannelAppList.js";
+export type { UseChannelAppListReturn } from "./useChannelAppList.js";
+export { useCreateChannelApp } from "./useCreateChannelApp.js";
+export type { UseCreateChannelAppReturn } from "./useCreateChannelApp.js";
+export { useUpdateChannelApp } from "./useUpdateChannelApp.js";
+export type { UseUpdateChannelAppReturn } from "./useUpdateChannelApp.js";
+export { useDeleteChannelApp } from "./useDeleteChannelApp.js";
+export type { UseDeleteChannelAppReturn } from "./useDeleteChannelApp.js";
+export { ChannelAppListPanel } from "./ChannelAppListPanel.js";
+export type { ChannelAppListPanelProps } from "./ChannelAppListPanel.js";
+export { CreateChannelAppForm } from "./CreateChannelAppForm.js";
+export type {
+  CreateChannelAppFormProps,
+  ChannelAppCreateHandoff,
+} from "./CreateChannelAppForm.js";
+export { ChannelAppDetailPanel } from "./ChannelAppDetailPanel.js";
+export type { ChannelAppDetailPanelProps } from "./ChannelAppDetailPanel.js";
+export {
+  buildSlackChannelAppManifest,
+  slackChannelAppRedirectUrl,
+  slackChannelAppWebhookUrl,
+  SLACK_CHANNEL_APP_BOT_EVENTS,
+  SLACK_CHANNEL_APP_BOT_SCOPES,
+} from "./slackAppSetup.js";
+export type { SlackChannelAppManifestInput } from "./slackAppSetup.js";
+export {
+  generateWhatsAppVerifyToken,
+  whatsappChannelAppWebhookUrl,
+  WHATSAPP_CHANNEL_APP_WEBHOOK_FIELDS,
+} from "./whatsappAppSetup.js";