@stigmer/react 3.1.17 → 3.2.0

package/src/channel-app/internal.tsx

@@ -0,0 +1,180 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { cn } from "@stigmer/theme";
+
+/**
+ * Internal building blocks shared by the channel-app forms and panels.
+ * Not exported from the package — content-level pieces stay domain-local.
+ */
+
+/** Labeled text/password input with an optional hint line. */
+export function FormField({
+  id,
+  label,
+  value,
+  onChange,
+  placeholder,
+  hint,
+  type = "text",
+  disabled,
+  required,
+}: {
+  id: string;
+  label: string;
+  value: string;
+  onChange: (v: string) => void;
+  placeholder: string;
+  hint?: string;
+  type?: "text" | "password";
+  disabled: boolean;
+  required?: boolean;
+}) {
+  return (
+    <div className="space-y-1">
+      <label htmlFor={id} className="text-xs font-medium text-foreground">
+        {label}
+      </label>
+      <input
+        id={id}
+        type={type}
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        placeholder={placeholder}
+        disabled={disabled}
+        required={required}
+        className={cn(
+          "w-full rounded-md border border-input bg-background px-2.5 py-1.5 text-xs text-foreground",
+          "placeholder:text-muted-foreground",
+          "focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring",
+          "disabled:pointer-events-none disabled:opacity-50",
+        )}
+      />
+      {hint && <p className="text-[0.65rem] text-muted-foreground">{hint}</p>}
+    </div>
+  );
+}
+
+/**
+ * A single-line copyable value (webhook URL, redirect URL) with a copy
+ * button that confirms briefly.
+ */
+export function CopyRow({
+  label,
+  value,
+  copyTargetId,
+}: {
+  label: string;
+  value: string;
+  copyTargetId?: string;
+}) {
+  const { copied, copy } = useCopy(value);
+
+  return (
+    <div className="space-y-1">
+      <p className="text-xs font-medium text-foreground">{label}</p>
+      <div className="flex items-center gap-1.5">
+        <code
+          className={cn(
+            "min-w-0 flex-1 truncate rounded-md border border-border bg-muted-subtle",
+            "px-2 py-1.5 font-mono text-[0.65rem] text-foreground",
+          )}
+          title={value}
+        >
+          {value}
+        </code>
+        <CopyButton copied={copied} onCopy={copy} copyTargetId={copyTargetId} />
+      </div>
+    </div>
+  );
+}
+
+/** A multi-line copyable value (the app manifest) in a scrollable block. */
+export function CopyBlock({
+  label,
+  value,
+  copyTargetId,
+}: {
+  label: string;
+  value: string;
+  copyTargetId?: string;
+}) {
+  const { copied, copy } = useCopy(value);
+
+  return (
+    <div className="space-y-1">
+      <div className="flex items-center justify-between">
+        <p className="text-[0.65rem] font-medium text-muted-foreground">
+          {label}
+        </p>
+        <CopyButton copied={copied} onCopy={copy} copyTargetId={copyTargetId} />
+      </div>
+      <pre
+        className={cn(
+          "max-h-40 overflow-auto rounded-md border border-border bg-muted-subtle",
+          "px-2.5 py-2 font-mono text-[0.65rem] leading-relaxed text-foreground",
+        )}
+      >
+        {value}
+      </pre>
+    </div>
+  );
+}
+
+function CopyButton({
+  copied,
+  onCopy,
+  copyTargetId,
+}: {
+  copied: boolean;
+  onCopy: () => void;
+  copyTargetId?: string;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onCopy}
+      data-cursor-target={copyTargetId}
+      className={cn(
+        "shrink-0 rounded-md border border-border px-2 py-1 text-[0.65rem] font-medium transition-colors",
+        copied
+          ? "text-success"
+          : "text-muted-foreground hover:text-foreground hover:bg-accent-hover",
+      )}
+      aria-live="polite"
+    >
+      {copied ? "Copied" : "Copy"}
+    </button>
+  );
+}
+
+function useCopy(value: string) {
+  const [copied, setCopied] = useState(false);
+
+  const copy = useCallback(() => {
+    void navigator.clipboard.writeText(value).then(() => {
+      setCopied(true);
+      window.setTimeout(() => setCopied(false), 1500);
+    });
+  }, [value]);
+
+  return { copied, copy };
+}
+
+export function SpinnerIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 16 16"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      className="animate-spin"
+      aria-hidden="true"
+    >
+      <path d="M8 2a6 6 0 1 0 6 6" />
+    </svg>
+  );
+}

package/src/channel-app/slackAppSetup.ts

@@ -0,0 +1,153 @@
+/**
+ * Pure helpers for the "bring your own Slack app" setup surface
+ * (T04 item 2).
+ *
+ * A customer-owned Slack app needs three Stigmer-side values wired into
+ * its configuration on api.slack.com: the OAuth redirect URL (shared by
+ * every app — the console's callback route), the app's own events
+ * webhook URL (per-app by design: the path is how the receiver knows
+ * which signing secret verifies the request), and the fixed scope/event
+ * sets. These helpers derive those values and render a ready-to-paste
+ * Slack app manifest so creating the app is one paste instead of a dozen
+ * dashboard steps.
+ *
+ * Setup is inherently two-phase — Slack mints the credentials, Stigmer
+ * mints the webhook URL, and each needs the other's output:
+ *
+ *  1. Create the Slack app from {@link buildSlackChannelAppManifest}
+ *     WITHOUT a webhook URL (events come later), then paste its
+ *     credentials into `CreateChannelAppForm`.
+ *  2. The saved ChannelApp has an id, so `ChannelAppDetailPanel` can show
+ *     the webhook URL — paste it into the app's Event Subscriptions (or
+ *     re-apply the completed manifest).
+ */
+
+/**
+ * The bot scopes every Stigmer channel app requests — the platform app's
+ * exact set (scope minimalism is deliberate: it is the first thing a
+ * workspace admin reviews on the consent screen).
+ */
+export const SLACK_CHANNEL_APP_BOT_SCOPES = [
+  "app_mentions:read",
+  "assistant:write",
+  "chat:write",
+  "im:history",
+] as const;
+
+/**
+ * The bot events every Stigmer channel app subscribes to — the platform
+ * app's exact set (mentions, DMs, assistant surface, and the uninstall/
+ * revocation lifecycle events).
+ */
+export const SLACK_CHANNEL_APP_BOT_EVENTS = [
+  "app_home_opened",
+  "app_mention",
+  "app_uninstalled",
+  "assistant_thread_context_changed",
+  "assistant_thread_started",
+  "message.im",
+  "tokens_revoked",
+] as const;
+
+/**
+ * The events webhook URL for one ChannelApp: the per-app route the
+ * receiver resolves the app's signing secret by.
+ *
+ * @param apiBaseUrl the Stigmer API origin (`stigmer.baseUrl`)
+ * @param channelAppId the ChannelApp resource id (`chapp_...`)
+ */
+export function slackChannelAppWebhookUrl(
+  apiBaseUrl: string,
+  channelAppId: string,
+): string {
+  return `${apiBaseUrl.replace(/\/+$/, "")}/webhook/slack/${channelAppId}`;
+}
+
+/**
+ * The OAuth redirect URL a customer registers on their Slack app — the
+ * console's install-callback route, shared by every app (the platform
+ * completes the code exchange server-side with the app's own
+ * credentials).
+ *
+ * @param consoleOrigin the console origin (defaults to the current
+ *                      window's origin; pass explicitly in non-browser
+ *                      hosts)
+ */
+export function slackChannelAppRedirectUrl(consoleOrigin?: string): string {
+  const origin =
+    consoleOrigin ??
+    (typeof window !== "undefined" ? window.location.origin : "");
+  return `${origin.replace(/\/+$/, "")}/oauth/slack/callback`;
+}
+
+/** Inputs for {@link buildSlackChannelAppManifest}. */
+export interface SlackChannelAppManifestInput {
+  /** Bot display name — what the workspace @mentions. */
+  readonly name: string;
+  /** One-line app description shown on the consent screen. */
+  readonly description?: string;
+  /** The console's OAuth redirect URL ({@link slackChannelAppRedirectUrl}). */
+  readonly redirectUrl: string;
+  /**
+   * The app's events webhook URL ({@link slackChannelAppWebhookUrl}).
+   * Omit before the ChannelApp exists — the manifest then skips event
+   * subscriptions, which are completed from the detail panel after
+   * creation.
+   */
+  readonly webhookUrl?: string;
+}
+
+/**
+ * Render the ready-to-paste Slack app manifest for a customer channel
+ * app — the platform app's manifest with the customer's identity.
+ *
+ * Deliberate mirrors of the platform manifest (do not "fix" them):
+ * four bot scopes only, `org_deploy_enabled: false` (Enterprise Grid
+ * org-wide installs are unsupported), no interactivity, no socket mode.
+ */
+export function buildSlackChannelAppManifest(
+  input: SlackChannelAppManifestInput,
+): string {
+  const description =
+    input.description ??
+    "Chat with your organization's Stigmer agent without leaving Slack.";
+
+  const eventSubscriptions = input.webhookUrl
+    ? `  event_subscriptions:
+    request_url: "${input.webhookUrl}"
+    bot_events:
+${SLACK_CHANNEL_APP_BOT_EVENTS.map((e) => `      - ${e}`).join("\n")}
+`
+    : "";
+
+  return `display_information:
+  name: ${input.name}
+  description: ${description}
+
+features:
+  app_home:
+    home_tab_enabled: false
+    messages_tab_enabled: true
+    messages_tab_read_only_enabled: false
+  bot_user:
+    display_name: ${input.name}
+    always_online: true
+  assistant_view:
+    assistant_description: ${description}
+    suggested_prompts: []
+
+oauth_config:
+  redirect_urls:
+    - "${input.redirectUrl}"
+  scopes:
+    bot:
+${SLACK_CHANNEL_APP_BOT_SCOPES.map((s) => `      - ${s}`).join("\n")}
+
+settings:
+${eventSubscriptions}  interactivity:
+    is_enabled: false
+  org_deploy_enabled: false
+  socket_mode_enabled: false
+  token_rotation_enabled: false
+`;
+}

package/src/channel-app/useChannelAppList.ts

@@ -0,0 +1,59 @@
+"use client";
+
+import { create } from "@bufbuild/protobuf";
+import { ListChannelAppsByOrgInputSchema } from "@stigmer/protos/ai/stigmer/agentic/channelapp/v1/io_pb";
+import type { ChannelApp } from "@stigmer/protos/ai/stigmer/agentic/channelapp/v1/api_pb";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+
+/** Return value of {@link useChannelAppList}. */
+export interface UseChannelAppListReturn {
+  /** Channel apps owned by the organization. Empty while loading or on error. */
+  readonly channelApps: readonly ChannelApp[];
+  /** `true` while the initial fetch or a refetch is in flight. */
+  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;
+  /** Discard cached data and re-fetch the list from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches all {@link ChannelApp} entries for an
+ * organization.
+ *
+ * These are the customer-owned messaging-platform apps (bring-your-own
+ * Slack apps) that agent channels can install through instead of the
+ * shared Stigmer app. Secret fields arrive redacted.
+ *
+ * Pass `null` for `org` to skip fetching (stable no-op). Useful when
+ * the active organization has not been resolved yet.
+ *
+ * @example
+ * ```tsx
+ * const { channelApps, isLoading, error } = useChannelAppList(org);
+ *
+ * if (isLoading) return <Spinner />;
+ * channelApps.map((app) => app.metadata?.name);
+ * ```
+ */
+export function useChannelAppList(
+  org: string | null,
+): UseChannelAppListReturn {
+  const stigmer = useStigmer();
+
+  const { data: channelApps, isLoading, isRefetching, error, refetch } = useFetch(
+    org
+      ? () =>
+          stigmer.channelapp
+            .listByOrg(create(ListChannelAppsByOrgInputSchema, { org }))
+            .then((r) => [...r.entries])
+      : null,
+    [org, stigmer],
+    [] as ChannelApp[],
+  );
+
+  return { channelApps, isLoading, isRefetching, error, refetch };
+}

package/src/channel-app/useCreateChannelApp.ts

@@ -0,0 +1,70 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { ChannelAppInput } from "@stigmer/sdk";
+import type { ChannelApp } from "@stigmer/protos/ai/stigmer/agentic/channelapp/v1/api_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+
+/** Return value of {@link useCreateChannelApp}. */
+export interface UseCreateChannelAppReturn {
+  /** Submit a {@link ChannelAppInput} to create a new channel app. Resolves with the server-created resource. */
+  readonly create: (input: ChannelAppInput) => Promise<ChannelApp>;
+  /** `true` while the create request is in flight. */
+  readonly isCreating: 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 wraps `channelapp.create()` with loading and error
+ * state.
+ *
+ * Creates a channel app — a customer-owned messaging-platform app whose
+ * credentials agent channels can install through instead of the shared
+ * Stigmer app. The secret fields (`clientSecret`, `signingSecret`) are
+ * encrypted server-side and come back redacted in the response.
+ *
+ * @example
+ * ```tsx
+ * const { create, isCreating, error } = useCreateChannelApp();
+ *
+ * const app = await create({
+ *   name: "Acme Support Bot",
+ *   org: "acme",
+ *   slack: {
+ *     clientId: "123456.789012",
+ *     clientSecret: "…",
+ *     signingSecret: "…",
+ *   },
+ * });
+ * ```
+ */
+export function useCreateChannelApp(): UseCreateChannelAppReturn {
+  const stigmer = useStigmer();
+  const [isCreating, setIsCreating] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const create = useCallback(
+    async (input: ChannelAppInput): Promise<ChannelApp> => {
+      setIsCreating(true);
+      setError(null);
+
+      try {
+        return await stigmer.channelapp.create(input);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsCreating(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { create, isCreating, error, clearError };
+}

package/src/channel-app/useDeleteChannelApp.ts

@@ -0,0 +1,62 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { ChannelApp } from "@stigmer/protos/ai/stigmer/agentic/channelapp/v1/api_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+
+/** Return value of {@link useDeleteChannelApp}. */
+export interface UseDeleteChannelAppReturn {
+  /** Delete a channel app by its resource ID. Resolves with the deleted resource for confirmation display. */
+  readonly deleteApp: (id: string) => Promise<ChannelApp>;
+  /** `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 wraps `channelapp.delete()` with loading and error
+ * state.
+ *
+ * Deletes a channel app by its resource ID. The server refuses
+ * (`FAILED_PRECONDITION`) while any agent channel still references the
+ * app via `spec.app_ref` — the error message names the fix; surface it
+ * to the user rather than retrying.
+ *
+ * @example
+ * ```tsx
+ * const { deleteApp, isDeleting, error } = useDeleteChannelApp();
+ *
+ * await deleteApp("chapp_abc123");
+ * refetch(); // refresh the list after deletion
+ * ```
+ */
+export function useDeleteChannelApp(): UseDeleteChannelAppReturn {
+  const stigmer = useStigmer();
+  const [isDeleting, setIsDeleting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const deleteApp = useCallback(
+    async (id: string): Promise<ChannelApp> => {
+      setIsDeleting(true);
+      setError(null);
+
+      try {
+        return await stigmer.channelapp.delete({ resourceId: id });
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsDeleting(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { deleteApp, isDeleting, error, clearError };
+}

package/src/channel-app/useUpdateChannelApp.ts

@@ -0,0 +1,70 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { ChannelAppInput } from "@stigmer/sdk";
+import type { ChannelApp } from "@stigmer/protos/ai/stigmer/agentic/channelapp/v1/api_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+
+/** Return value of {@link useUpdateChannelApp}. */
+export interface UseUpdateChannelAppReturn {
+  /** Submit a {@link ChannelAppInput} to update an existing channel app. Resolves with the updated resource. */
+  readonly update: (input: ChannelAppInput) => Promise<ChannelApp>;
+  /** `true` while the update request is in flight. */
+  readonly isUpdating: boolean;
+  /** Error from the last failed update, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Mutation hook that wraps `channelapp.update()` with loading and error
+ * state.
+ *
+ * Updates an existing channel app — typically to rotate its secrets.
+ * Sending the redaction marker (`***REDACTED***`) for a secret field
+ * preserves the stored value, so a form prefilled from a fetched
+ * (redacted) app can rotate one secret without re-entering the other.
+ *
+ * @example
+ * ```tsx
+ * const { update, isUpdating, error } = useUpdateChannelApp();
+ *
+ * await update({
+ *   name: "Acme Support Bot",
+ *   org: "acme",
+ *   slack: {
+ *     clientId: "123456.789012",
+ *     clientSecret: "***REDACTED***",   // keep the stored value
+ *     signingSecret: "new-signing-secret", // rotate this one
+ *   },
+ * });
+ * ```
+ */
+export function useUpdateChannelApp(): UseUpdateChannelAppReturn {
+  const stigmer = useStigmer();
+  const [isUpdating, setIsUpdating] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const update = useCallback(
+    async (input: ChannelAppInput): Promise<ChannelApp> => {
+      setIsUpdating(true);
+      setError(null);
+
+      try {
+        return await stigmer.channelapp.update(input);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsUpdating(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { update, isUpdating, error, clearError };
+}

package/src/channel-app/whatsappAppSetup.ts

@@ -0,0 +1,62 @@
+/**
+ * Pure helpers for the "bring your own Meta app" setup surface (T05).
+ *
+ * A customer-owned Meta app needs two Stigmer-side values wired into its
+ * WhatsApp webhook configuration on developers.facebook.com: the app's
+ * own events webhook URL (per-app by design: the path is how the
+ * receiver knows which app secret verifies the request) and the verify
+ * token Meta echoes during the GET verification handshake.
+ *
+ * Unlike Slack there is no app manifest to paste — Meta's dashboard has
+ * no equivalent — so the setup surface renders a checklist instead. And
+ * unlike Slack's install-minted bot token, every WhatsApp credential is
+ * authored by the customer on their own Meta app (DD-WA-3), including
+ * the verify token: Stigmer generates a strong one at registration as a
+ * convenience, and it must be pasted into Meta verbatim.
+ *
+ * Setup is inherently two-phase, same shape as Slack: the webhook URL
+ * embeds the ChannelApp id, which only exists after registration:
+ *
+ *  1. Gather the Meta app's credentials (app ID, app secret, a
+ *     long-lived access token) and register them with a verify token in
+ *     `CreateChannelAppForm`.
+ *  2. The saved ChannelApp has an id, so `ChannelAppDetailPanel` can
+ *     show the webhook URL — paste it and the verify token into the
+ *     app's WhatsApp webhook configuration.
+ */
+
+/**
+ * The webhook fields every Stigmer WhatsApp channel app subscribes to —
+ * inbound messages only (field minimalism is deliberate; the adapter
+ * replies to inbound messages and needs nothing else).
+ */
+export const WHATSAPP_CHANNEL_APP_WEBHOOK_FIELDS = ["messages"] as const;
+
+/**
+ * The events webhook URL for one ChannelApp: the per-app route the
+ * receiver resolves the app's secret and verify token by.
+ *
+ * @param apiBaseUrl the Stigmer API origin (`stigmer.baseUrl`)
+ * @param channelAppId the ChannelApp resource id (`chapp_...`)
+ */
+export function whatsappChannelAppWebhookUrl(
+  apiBaseUrl: string,
+  channelAppId: string,
+): string {
+  return `${apiBaseUrl.replace(/\/+$/, "")}/webhook/whatsapp/${channelAppId}`;
+}
+
+/**
+ * Generate a verify token for a new WhatsApp channel app: 32 bytes of
+ * CSPRNG randomness as lowercase hex (64 chars, paste-safe — no
+ * URL-hostile characters for Meta's form).
+ *
+ * The token is a shared secret in the weakest sense — Meta echoes it on
+ * the one-time GET handshake — but a guessable one would let a stranger
+ * "verify" a webhook they control, so it gets real entropy anyway.
+ */
+export function generateWhatsAppVerifyToken(): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}

package/src/environment/index.ts

@@ -50,6 +50,8 @@ export {
 } from "./systemEnvVars.js";
 export { EnvironmentPicker } from "./EnvironmentPicker.js";
 export type { EnvironmentPickerProps } from "./EnvironmentPicker.js";
+export { useToolCredentialsReadiness } from "./useToolCredentialsReadiness.js";
+export type { ToolCredentialsReadiness } from "./useToolCredentialsReadiness.js";
 export {
   PERSONAL_ENV_LABEL,
   MANAGED_ENV_LABEL,