@stigmer/react 3.1.17 → 3.2.0

package/src/channel/useCreateAgentChannel.ts

@@ -0,0 +1,73 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { AgentChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
+import type { AgentChannelInput } from "@stigmer/sdk";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+
+/** Return value of {@link useCreateAgentChannel}. */
+export interface UseCreateAgentChannelReturn {
+  /**
+   * Create a new agent channel (strict create: an existing org + slug
+   * fails with ALREADY_EXISTS rather than silently updating it — the
+   * reason this is not `apply`). Returns the created resource in
+   * `pending_install` state; run the provider install flow next.
+   */
+  readonly createChannel: (input: AgentChannelInput) => Promise<AgentChannel>;
+  /** `true` while the create request is in flight. */
+  readonly isPending: boolean;
+  /** Error from the last failed create, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Mutation hook that creates an {@link AgentChannel}.
+ *
+ * Wraps `stigmer.agentChannel.create()` with loading/error state. An
+ * agent can carry several channels (e.g. two Slack workspaces), so a new
+ * channel must never overwrite a sibling whose derived slug collides —
+ * strict-create semantics make that mistake loud instead of silent.
+ * Updates and toggles go through `useSaveAgentChannel` (apply).
+ *
+ * @example
+ * ```tsx
+ * const { createChannel, isPending } = useCreateAgentChannel();
+ *
+ * const channel = await createChannel({
+ *   name: "Support Slack",
+ *   org: agent.metadata.org,
+ *   agentRef: { org: agent.metadata.org, slug: agent.metadata.slug },
+ *   enabled: true,
+ *   slack: {},
+ * });
+ * ```
+ */
+export function useCreateAgentChannel(): UseCreateAgentChannelReturn {
+  const stigmer = useStigmer();
+  const [isPending, setIsPending] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const createChannel = useCallback(
+    async (input: AgentChannelInput): Promise<AgentChannel> => {
+      setIsPending(true);
+      setError(null);
+
+      try {
+        return await stigmer.agentChannel.create(input);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsPending(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { createChannel, isPending, error, clearError };
+}

package/src/channel/useDeleteAgentChannel.ts

@@ -0,0 +1,71 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { AgentChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+
+/** Return value of {@link useDeleteAgentChannel}. */
+export interface UseDeleteAgentChannelReturn {
+  /**
+   * Delete an agent channel by ID. Returns the deleted resource.
+   *
+   * Deleting a channel is full teardown: the provider connection stops
+   * serving immediately and the stored install (including its
+   * credentials) is removed. To stop serving while keeping the install,
+   * save the channel with `enabled: false` instead (a config-preserving
+   * pause via `useSaveAgentChannel`).
+   */
+  readonly deleteChannel: (id: string) => Promise<AgentChannel>;
+  /** `true` while the delete request is in flight. */
+  readonly isDeleting: boolean;
+  /** Error from the last failed delete, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Mutation hook that deletes an {@link AgentChannel} resource.
+ *
+ * Wraps `stigmer.agentChannel.delete()` with loading/error state. The
+ * caller is responsible for post-delete UI updates (e.g. refreshing the
+ * channel list) and for confirming the destructive action — the
+ * delete-vs-pause distinction belongs in the confirmation copy.
+ *
+ * @example
+ * ```tsx
+ * const { deleteChannel, isDeleting } = useDeleteAgentChannel();
+ *
+ * const handleDelete = async () => {
+ *   await deleteChannel(channel.metadata.id);
+ *   refetch(); // refresh the channel list
+ * };
+ * ```
+ */
+export function useDeleteAgentChannel(): UseDeleteAgentChannelReturn {
+  const stigmer = useStigmer();
+  const [isDeleting, setIsDeleting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const deleteChannel = useCallback(
+    async (id: string): Promise<AgentChannel> => {
+      setIsDeleting(true);
+      setError(null);
+
+      try {
+        return await stigmer.agentChannel.delete(id);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsDeleting(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { deleteChannel, isDeleting, error, clearError };
+}

package/src/channel/useInstallChannel.ts

@@ -0,0 +1,117 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { create } from "@bufbuild/protobuf";
+import { InitiateChannelInstallInputSchema } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/io_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+
+/**
+ * Progress phases of a direct channel install.
+ *
+ * One live phase only — a direct install has no consent redirect and no
+ * code exchange; the whole flow is the single `initiateInstall` call.
+ */
+export type InstallChannelPhase = "idle" | "installing" | "done";
+
+/** Return value of {@link useInstallChannel}. */
+export interface UseInstallChannelReturn {
+  /**
+   * Run the direct install flow for a channel.
+   *
+   * One `initiateInstall` call does everything: the server validates the
+   * declared provider identity against the provider's API, persists the
+   * install facts on status, and answers `completed=true` (DD-WA-1).
+   * Works for first installs and retries of a pending channel alike.
+   *
+   * The server's `completed` field is the authoritative outcome
+   * (DD-WA-1b): `false` means this channel's provider actually wants the
+   * redirect flow — surfaced as an error rather than silently ignored,
+   * because this hook cannot run a consent redirect.
+   *
+   * Failure modes surface as `error` with server-authored copy: bad or
+   * expired app credentials, an unrecognized provider identity, a
+   * dangling app reference, or a duplicate install (carrying a
+   * `google.rpc.ErrorInfo` reason readable via `getErrorReason`).
+   *
+   * @param channelId - System-generated ID (metadata.id) of the channel.
+   */
+  readonly install: (channelId: string) => Promise<void>;
+  /** `true` while the install call is in flight. */
+  readonly isInProgress: boolean;
+  /** Current phase of the install flow. */
+  readonly phase: InstallChannelPhase;
+  /** Error from the most recent unsuccessful attempt, or `null`. */
+  readonly error: Error | null;
+  /** Reset the hook to idle state. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that runs a direct (non-redirect) channel install —
+ * WhatsApp today ({@link useConnectSlackChannel} is the redirect
+ * counterpart). No popup, no callback route, no `completeInstall`.
+ *
+ * `initiateInstall` does not return the channel — callers refetch their
+ * channel (list) afterwards to observe the `installed` state, exactly
+ * like every other mutation-then-refetch flow in this package.
+ *
+ * @example
+ * ```tsx
+ * const installer = useInstallChannel();
+ *
+ * async function handleConnect() {
+ *   await installer.install(channel.metadata.id);
+ *   refetch();
+ * }
+ * ```
+ */
+export function useInstallChannel(): UseInstallChannelReturn {
+  const stigmer = useStigmer();
+  const [phase, setPhase] = useState<InstallChannelPhase>("idle");
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => {
+    setPhase("idle");
+    setError(null);
+  }, []);
+
+  const install = useCallback(
+    async (channelId: string): Promise<void> => {
+      setPhase("installing");
+      setError(null);
+
+      try {
+        const output = await stigmer.agentChannel.initiateInstall(
+          create(InitiateChannelInstallInputSchema, { resourceId: channelId }),
+        );
+
+        if (!output.completed) {
+          // The server says this provider installs via consent redirect —
+          // a wiring error (the caller routed a redirect-style provider
+          // to the direct hook), not a user-fixable condition.
+          throw new Error(
+            "This channel's provider requires an interactive install — " +
+              "connect it through its provider flow instead.",
+          );
+        }
+
+        setPhase("done");
+      } catch (err) {
+        const wrapped = toError(err);
+        setError(wrapped);
+        setPhase("idle");
+        throw wrapped;
+      }
+    },
+    [stigmer],
+  );
+
+  return {
+    install,
+    isInProgress: phase === "installing",
+    phase,
+    error,
+    clearError,
+  };
+}

package/src/channel/useOrgAgentChannelList.ts

@@ -0,0 +1,60 @@
+"use client";
+
+import { create } from "@bufbuild/protobuf";
+import type { AgentChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
+import { ListAgentChannelsRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/io_pb";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+
+/** Return value of {@link useOrgAgentChannelList}. */
+export interface UseOrgAgentChannelListReturn {
+  /**
+   * The organization's channels visible to the caller, across all its
+   * agents, in server order. Empty while loading, on error, or when the
+   * org has none.
+   */
+  readonly channels: readonly AgentChannel[];
+  /** `true` while the initial fetch is in flight and no data is shown. */
+  readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale data is shown. */
+  readonly isRefetching: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Re-fetch the channels from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that loads an organization's {@link AgentChannel} resources
+ * across all its agents — the org-wide view {@link useAgentChannelList}
+ * (per-agent) cannot provide.
+ *
+ * The connect flow uses it to tell the user which workspaces a serving
+ * app already occupies before they start the provider OAuth. The view is
+ * permission-bounded (FGA-filtered in cloud), so treat it as advisory —
+ * the database uniqueness index remains the arbiter.
+ *
+ * Pass `null` for `org` to skip fetching (stable no-op).
+ */
+export function useOrgAgentChannelList(
+  org: string | null,
+): UseOrgAgentChannelListReturn {
+  const stigmer = useStigmer();
+
+  const fetchFn = org
+    ? async () => {
+        const result = await stigmer.agentChannel.list(
+          create(ListAgentChannelsRequestSchema, { org }),
+        );
+        return result.items;
+      }
+    : null;
+
+  const { data: channels, isLoading, isRefetching, error, refetch } = useFetch(
+    fetchFn,
+    [org, stigmer],
+    [] as AgentChannel[],
+  );
+
+  return { channels, isLoading, isRefetching, error, refetch };
+}

package/src/channel/useSaveAgentChannel.ts

@@ -0,0 +1,133 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { AgentChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
+import type { AgentChannelInput } from "@stigmer/sdk";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+
+/**
+ * Rebuild the {@link AgentChannelInput} that reproduces an existing
+ * channel verbatim.
+ *
+ * `apply` replaces the channel's whole spec, so a caller toggling one
+ * field must supply the full configuration — this helper makes that safe:
+ *
+ * ```ts
+ * save({ ...agentChannelToInput(channel), enabled: false });
+ * ```
+ *
+ * Provider config carries over per arm: the Slack config is an empty
+ * marker message in v1 (all concrete facts are OAuth-observed and live
+ * in `status`, which survives every save verbatim); the WhatsApp config
+ * carries its declared `phone_number_id`. Dropping the arm is never an
+ * option — the provider oneof is immutable server-side, so a save
+ * without it would be refused outright. The channel's bound tool
+ * credentials (`environment_refs`) and its channel-app binding
+ * (`app_ref`) carry over too — apply semantics would otherwise silently
+ * unbind them on every toggle (and an installed channel's app_ref is
+ * frozen server-side, so dropping it would refuse the save outright).
+ */
+export function agentChannelToInput(channel: AgentChannel): AgentChannelInput {
+  const metadata = channel.metadata;
+  const spec = channel.spec;
+  const labels = metadata?.labels ?? {};
+  const environmentRefs = spec?.environmentRefs ?? [];
+
+  return {
+    name: metadata?.name ?? "",
+    ...(metadata?.slug ? { slug: metadata.slug } : {}),
+    org: metadata?.org ?? "",
+    ...(Object.keys(labels).length > 0 ? { labels: { ...labels } } : {}),
+    ...(metadata?.visibility ? { visibility: metadata.visibility } : {}),
+    agentRef: {
+      org: spec?.agentRef?.org ?? "",
+      slug: spec?.agentRef?.slug ?? "",
+    },
+    enabled: spec?.enabled ?? false,
+    ...(spec?.providerConfig?.case === "slack" ? { slack: {} } : {}),
+    ...(spec?.providerConfig?.case === "whatsapp"
+      ? { whatsapp: { phoneNumberId: spec.providerConfig.value.phoneNumberId } }
+      : {}),
+    ...(spec?.appRef?.slug
+      ? {
+          appRef: {
+            org: spec.appRef.org,
+            slug: spec.appRef.slug,
+          },
+        }
+      : {}),
+    ...(environmentRefs.length > 0
+      ? {
+          environmentRefs: environmentRefs.map((ref) => ({
+            org: ref.org,
+            slug: ref.slug,
+          })),
+        }
+      : {}),
+  };
+}
+
+/** Return value of {@link useSaveAgentChannel}. */
+export interface UseSaveAgentChannelReturn {
+  /**
+   * Create or update an agent channel (`apply` semantics: upsert by
+   * org + slug). Returns the persisted resource.
+   *
+   * Disabling is a config-preserving pause: save with `enabled: false`
+   * and the provider install (and its credentials) survive. Deleting is
+   * the full teardown — see `useDeleteAgentChannel`.
+   */
+  readonly save: (input: AgentChannelInput) => Promise<AgentChannel>;
+  /** `true` while the save request is in flight. */
+  readonly isPending: boolean;
+  /** Error from the last failed save, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Mutation hook that creates or updates an {@link AgentChannel}.
+ *
+ * Wraps `stigmer.agentChannel.apply()` with loading/error state. The
+ * caller is responsible for post-save UI updates (e.g. refreshing the
+ * channel list). Pair with {@link agentChannelToInput} to change a single
+ * field of an existing channel without dropping the rest of its spec.
+ *
+ * @example
+ * ```tsx
+ * const { save, isPending } = useSaveAgentChannel();
+ *
+ * const handleToggle = async (channel: AgentChannel, enabled: boolean) => {
+ *   await save({ ...agentChannelToInput(channel), enabled });
+ *   refetch(); // refresh the channel list
+ * };
+ * ```
+ */
+export function useSaveAgentChannel(): UseSaveAgentChannelReturn {
+  const stigmer = useStigmer();
+  const [isPending, setIsPending] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const save = useCallback(
+    async (input: AgentChannelInput): Promise<AgentChannel> => {
+      setIsPending(true);
+      setError(null);
+
+      try {
+        return await stigmer.agentChannel.apply(input);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsPending(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { save, isPending, error, clearError };
+}