@invect/ui 0.0.1

package/src/stores/flowEditorStore.ts

@@ -0,0 +1,2 @@
+// Re-export from canonical location for backwards compatibility
+export * from '../components/flow-editor/flow-editor.store';

package/src/stores/index.ts

@@ -0,0 +1,10 @@
+// Zustand stores for Invect frontend state management
+//
+// Architecture:
+// - React Query: Server state (API data, caching, sync)
+// - Zustand: Client state (UI state, selections, local mutations before save)
+//
+// Key principle: Never duplicate server state in Zustand
+
+export * from './uiStore';
+export * from './executionViewStore';

package/src/stores/uiStore.ts

@@ -0,0 +1,189 @@
+import { create, type StoreApi, type UseBoundStore } from 'zustand';
+import { devtools, persist } from 'zustand/middleware';
+import { immer } from 'zustand/middleware/immer';
+
+export type ModalType =
+  | 'createFlow'
+  | 'createCredential'
+  | 'editCredential'
+  | 'confirm'
+  | 'executeFlow'
+  | 'deleteConfirm'
+  | null;
+
+export type SidebarTab = 'nodes' | 'settings' | 'history';
+
+interface UIState {
+  // Sidebar
+  sidebarCollapsed: boolean;
+  activeSidebarTab: SidebarTab;
+
+  // Modals
+  activeModal: ModalType;
+  modalData: Record<string, unknown>;
+
+  // Panels
+  validationPanelOpen: boolean;
+  logsPanelOpen: boolean;
+
+  // Node sidebar (for adding nodes)
+  nodeSidebarOpen: boolean;
+
+  // Bottom toolbar
+  toolbarCollapsed: boolean;
+}
+
+interface UIActions {
+  // Sidebar
+  toggleSidebar: () => void;
+  setSidebarCollapsed: (collapsed: boolean) => void;
+  setSidebarTab: (tab: SidebarTab) => void;
+
+  // Modals
+  openModal: (modal: NonNullable<ModalType>, data?: Record<string, unknown>) => void;
+  closeModal: () => void;
+  setModalData: (data: Record<string, unknown>) => void;
+
+  // Panels
+  toggleValidationPanel: () => void;
+  setValidationPanelOpen: (open: boolean) => void;
+  toggleLogsPanel: () => void;
+  setLogsPanelOpen: (open: boolean) => void;
+
+  // Node sidebar
+  toggleNodeSidebar: () => void;
+  setNodeSidebarOpen: (open: boolean) => void;
+
+  // Bottom toolbar
+  toggleToolbarCollapsed: () => void;
+
+  // Reset
+  reset: () => void;
+}
+
+export type UIStore = UIState & UIActions;
+
+const initialState: UIState = {
+  sidebarCollapsed: false,
+  activeSidebarTab: 'nodes',
+  activeModal: null,
+  modalData: {},
+  validationPanelOpen: false,
+  logsPanelOpen: false,
+  nodeSidebarOpen: true,
+  toolbarCollapsed: false,
+};
+
+export const useUIStore: UseBoundStore<StoreApi<UIStore>> = create<UIStore>()(
+  devtools(
+    persist(
+      immer((set) => ({
+        ...initialState,
+
+        // Sidebar
+        toggleSidebar: () =>
+          set((state) => {
+            state.sidebarCollapsed = !state.sidebarCollapsed;
+          }),
+
+        setSidebarCollapsed: (collapsed) =>
+          set((state) => {
+            state.sidebarCollapsed = collapsed;
+          }),
+
+        setSidebarTab: (tab) =>
+          set((state) => {
+            state.activeSidebarTab = tab;
+          }),
+
+        // Modals
+        openModal: (modal, data = {}) =>
+          set((state) => {
+            state.activeModal = modal;
+            state.modalData = data;
+          }),
+
+        closeModal: () =>
+          set((state) => {
+            state.activeModal = null;
+            state.modalData = {};
+          }),
+
+        setModalData: (data) =>
+          set((state) => {
+            state.modalData = { ...state.modalData, ...data };
+          }),
+
+        // Panels
+        toggleValidationPanel: () =>
+          set((state) => {
+            state.validationPanelOpen = !state.validationPanelOpen;
+          }),
+
+        setValidationPanelOpen: (open) =>
+          set((state) => {
+            state.validationPanelOpen = open;
+          }),
+
+        toggleLogsPanel: () =>
+          set((state) => {
+            state.logsPanelOpen = !state.logsPanelOpen;
+          }),
+
+        setLogsPanelOpen: (open) =>
+          set((state) => {
+            state.logsPanelOpen = open;
+          }),
+
+        // Node sidebar
+        toggleNodeSidebar: () =>
+          set((state) => {
+            state.nodeSidebarOpen = !state.nodeSidebarOpen;
+          }),
+
+        setNodeSidebarOpen: (open) =>
+          set((state) => {
+            state.nodeSidebarOpen = open;
+          }),
+
+        // Bottom toolbar
+        toggleToolbarCollapsed: () =>
+          set((state) => {
+            state.toolbarCollapsed = !state.toolbarCollapsed;
+          }),
+
+        // Reset
+        reset: () => set(() => ({ ...initialState })),
+      })),
+      {
+        name: 'invect-ui',
+        // Only persist certain fields
+        partialize: (state) => ({
+          sidebarCollapsed: state.sidebarCollapsed,
+          activeSidebarTab: state.activeSidebarTab,
+          nodeSidebarOpen: state.nodeSidebarOpen,
+          toolbarCollapsed: state.toolbarCollapsed,
+        }),
+      },
+    ),
+    { name: 'ui' },
+  ),
+);
+
+// Selector hooks
+export const useSidebarCollapsed = () => useUIStore((s) => s.sidebarCollapsed);
+export const useActiveSidebarTab = () => useUIStore((s) => s.activeSidebarTab);
+export const useActiveModal = () => useUIStore((s) => s.activeModal);
+export const useModalData = () => useUIStore((s) => s.modalData);
+export const useValidationPanelOpen = () => useUIStore((s) => s.validationPanelOpen);
+export const useLogsPanelOpen = () => useUIStore((s) => s.logsPanelOpen);
+export const useNodeSidebarOpen = () => useUIStore((s) => s.nodeSidebarOpen);
+
+// Combined selectors
+export const useModals = () =>
+  useUIStore((s) => ({
+    activeModal: s.activeModal,
+    modalData: s.modalData,
+    openModal: s.openModal,
+    closeModal: s.closeModal,
+  }));

package/src/types/agent-tools.types.ts

@@ -0,0 +1,64 @@
+/**
+ * Agent Tool Types for Frontend
+ *
+ * Types for displaying and managing agent tools in the UI.
+ * These align with AgentToolDefinition from @invect/core.
+ */
+
+import type { AppendixPosition } from '../components/nodes/NodeAppendix';
+
+/**
+ * Tool category for organization in UI
+ * Matches AgentToolCategory from @invect/core
+ */
+export type ToolCategory = 'data' | 'web' | 'code' | 'utility' | 'custom';
+
+/**
+ * Simplified tool definition for display in the UI
+ * Matches the essential fields from AgentToolDefinition in core
+ */
+export interface AgentToolDisplay {
+  /** Unique tool identifier (snake_case) */
+  id: string;
+  /** Human-readable name */
+  name: string;
+  /** Tool category for organization and styling */
+  category: ToolCategory;
+  /** Description (optional for display, shown in tooltips) */
+  description?: string;
+}
+
+/**
+ * Convert from backend AgentToolDefinition to frontend display format
+ * This is a utility type - the actual conversion is done in components
+ */
+export type AgentToolDefinitionToDisplay<
+  T extends { id: string; name: string; category: ToolCategory; description?: string },
+> = Pick<T, 'id' | 'name' | 'category' | 'description'>;
+
+/**
+ * Agent node data extensions for tools
+ */
+export interface AgentNodeToolsData {
+  /** Resolved tools for display (populated by frontend from API) */
+  tools?: AgentToolDisplay[];
+  /** Position of the tools appendix */
+  toolsPosition?: AppendixPosition;
+}
+
+/**
+ * Event handlers for agent tool interactions
+ */
+export interface AgentToolHandlers {
+  /** Called when user clicks "Add Tool" button */
+  onAddTool?: () => void;
+  /** Called when user clicks on a tool (to configure it) */
+  onToolClick?: (tool: AgentToolDisplay) => void;
+  /** Called when user clicks remove button on a tool */
+  onRemoveTool?: (toolId: string) => void;
+  /** Called when user changes the tools appendix position */
+  onToolsPositionChange?: (position: AppendixPosition) => void;
+}
+
+// Re-export for convenience
+export type { AppendixPosition };

package/src/types/index.ts

@@ -0,0 +1,5 @@
+// Node definition types - export from the more complete one
+export * from './node-definition.types';
+
+// Agent tool types for UI
+export * from './agent-tools.types';

package/src/types/node-definition.types.ts

@@ -0,0 +1,104 @@
+export interface NodeHandleDefinition {
+  id: string;
+  label: string;
+  type: string; // e.g., "string", "object", "any"
+  required?: boolean;
+  description?: string;
+}
+
+export interface NodeParamField {
+  name: string;
+  label: string;
+  type:
+    | 'text'
+    | 'textarea'
+    | 'select'
+    | 'number'
+    | 'boolean'
+    | 'json'
+    | 'code'
+    | 'credential'
+    | 'switch-cases';
+  description?: string;
+  placeholder?: string;
+  defaultValue?: unknown;
+  options?: { label: string; value: string | number; description?: string }[]; // For select
+  required?: boolean;
+  hidden?: boolean; // For internal params
+  disabled?: boolean;
+  extended?: boolean; // If true, field is shown in "More Options" collapsed section
+
+  // Credential field options (only used when type="credential")
+  credentialTypes?: ('oauth2' | 'api_key' | 'basic_auth' | 'database' | 'llm')[]; // Filter credentials by auth type or credential type
+  oauth2Providers?: string[]; // Filter OAuth2 credentials by provider ID (e.g., "google")
+  requiredScopes?: string[]; // OAuth2 scopes this node needs (used instead of provider defaults)
+
+  // Dynamic option loading metadata (serialised from action's loadOptions config)
+  /** When present, this field's options should be loaded from the server. */
+  loadOptions?: {
+    /** Sibling field names that trigger a reload when they change. */
+    dependsOn: string[];
+  };
+}
+
+export interface NodeDefinition {
+  /**
+   * Node type identifier. Can be a GraphNodeType enum value (e.g. "MODEL")
+   * or a provider action ID (e.g. "gmail.list_messages").
+   */
+  type: string;
+  label: string;
+  description: string;
+  icon?: string; // Icon name
+
+  /**
+   * Provider info for grouping in the node palette.
+   * Actions populate this from their ProviderDef; legacy nodes may leave it undefined.
+   */
+  provider?: {
+    id: string;
+    name: string;
+    icon?: string;
+    /** Raw SVG markup for custom provider branding. Takes precedence over `icon`. */
+    svgIcon?: string;
+  };
+
+  /**
+   * Single unified input handle definition. Undefined when the node does not accept inbound edges (e.g. Flow Input node).
+   */
+  input?: NodeHandleDefinition;
+
+  /**
+   * Fixed output handles.
+   * For nodes with `dynamicOutputs`, these are placeholders —
+   * the frontend derives actual handles from the node's params.
+   */
+  outputs: NodeHandleDefinition[];
+
+  /**
+   * When true, output handles are derived from the node's params at render
+   * time (e.g. switch node cases) instead of using the static `outputs` array.
+   */
+  dynamicOutputs?: boolean;
+
+  /**
+   * Configuration fields for the node (displayed in the sidebar/form).
+   */
+  paramFields: NodeParamField[];
+
+  /**
+   * Default values for parameters.
+   */
+  defaultParams?: Record<string, unknown>;
+
+  /**
+   * Maximum number of instances of this node type allowed per flow.
+   * Undefined = unlimited.
+   */
+  maxInstances?: number;
+
+  /**
+   * When true, hide this node from the palette (deprecated but still executable).
+   */
+  hidden?: boolean;
+}

package/src/types/plugin.types.ts

@@ -0,0 +1,123 @@
+/**
+ * Frontend Plugin Types
+ *
+ * Defines the extension points that frontend plugins can contribute to.
+ * These types are consumed by the PluginRegistryContext and the Invect
+ * component to render plugin-contributed UI elements.
+ */
+
+import type { ComponentType, ReactNode } from 'react';
+
+// ─────────────────────────────────────────────────────────────
+// Frontend Plugin Interface
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * A frontend plugin that contributes UI to the Invect application.
+ * Plugins are registered via `<Invect plugins={[myPlugin]} />`.
+ */
+export interface InvectFrontendPlugin {
+  /** Unique plugin ID — should match backend plugin ID for manifest resolution */
+  id: string;
+
+  /** Display name */
+  name?: string;
+
+  /** Add items to the sidebar navigation */
+  sidebar?: PluginSidebarContribution[];
+
+  /**
+   * Component rendered at the very bottom of the sidebar.
+   * Receives `collapsed` and `basePath` props to adapt layout and build links.
+   * Typically used for user avatar / profile link.
+   * Only the first plugin that provides this wins.
+   */
+  sidebarFooter?: ComponentType<{ collapsed: boolean; basePath: string }>;
+
+  /** Add top-level routes (pages) */
+  routes?: PluginRouteContribution[];
+
+  /** Add tabs to contextual panels (flow editor right panel, etc.) */
+  panelTabs?: PluginPanelTabContribution[];
+
+  /** Add action buttons/components to contextual headers */
+  headerActions?: PluginHeaderActionContribution[];
+
+  /**
+   * Named component implementations — resolved from backend componentIds.
+   * Key = componentId (e.g. 'rbac.FlowAccessPanel'), value = React component.
+   */
+  components?: Record<string, ComponentType<Record<string, unknown>>>;
+
+  /** Wrap the React tree with additional providers (auth context, etc.) */
+  providers?: ComponentType<{ children: ReactNode }>[];
+
+  /**
+   * Inject headers into every API request.
+   * Called before each request. Return headers to merge.
+   */
+  apiHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+
+  /**
+   * Check if the current user has a specific permission.
+   * Returns true/false to override, or undefined to defer to default.
+   */
+  checkPermission?: (permission: string, context?: PermissionContext) => boolean | undefined;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Contribution Types
+// ─────────────────────────────────────────────────────────────
+
+export interface PluginSidebarContribution {
+  label: string;
+  icon: ComponentType<{ className?: string }>;
+  path: string;
+  /** Badge text or function returning badge text */
+  badge?: string | (() => string | undefined);
+  /** Position hint: 'top' (after defaults), 'bottom' (before theme toggle) */
+  position?: 'top' | 'bottom';
+  /** Required permission — item hidden if check fails */
+  permission?: string;
+}
+
+export interface PluginRouteContribution {
+  path: string;
+  component: ComponentType<{ basePath: string }>;
+  /** If true, route is nested under the flow layout */
+  flowScoped?: boolean;
+}
+
+export interface PluginPanelTabContribution {
+  /** Where the tab appears */
+  context: 'flowEditor' | 'nodeConfig';
+  label: string;
+  icon?: ComponentType<{ className?: string }>;
+  component: ComponentType<PanelTabProps>;
+  /** Required permission — tab hidden if check fails */
+  permission?: string;
+}
+
+export interface PluginHeaderActionContribution {
+  /** Where the action appears */
+  context: 'flowHeader' | 'flowList';
+  component: ComponentType<HeaderActionProps>;
+  /** Required permission — action hidden if check fails */
+  permission?: string;
+}
+
+export interface PanelTabProps {
+  flowId: string;
+  basePath: string;
+}
+
+export interface HeaderActionProps {
+  flowId?: string;
+  basePath: string;
+}
+
+export interface PermissionContext {
+  resourceType?: string;
+  resourceId?: string;
+  flowId?: string;
+}

package/src/utils/credentialBranding.ts

@@ -0,0 +1,116 @@
+import type { Credential } from '../api/types';
+
+const OAUTH2_TO_ICON_ID: Record<string, string> = {
+  google: 'google',
+  microsoft: 'microsoft',
+  github: 'github',
+  slack: 'slack',
+  linear: 'linear',
+};
+
+const NAME_HINTS: Array<[RegExp, string, string]> = [
+  [/openai|gpt/i, 'openai', 'Zap'],
+  [/anthropic|claude/i, 'anthropic', 'Zap'],
+  [/openrouter/i, 'openrouter', 'Bot'],
+  [/gmail/i, 'google', 'Mail'],
+  [/github/i, 'github', 'Github'],
+  [/slack/i, 'slack', 'MessageSquare'],
+  [/linear/i, 'linear', 'CheckSquare'],
+  [/google/i, 'google', 'Globe'],
+  [/postgres/i, 'postgres', 'Database'],
+];
+
+const URL_HINTS: Array<[RegExp, string, string]> = [
+  [/openai/i, 'openai', 'Zap'],
+  [/anthropic/i, 'anthropic', 'Zap'],
+  [/openrouter/i, 'openrouter', 'Bot'],
+  [/github/i, 'github', 'Github'],
+  [/slack/i, 'slack', 'MessageSquare'],
+];
+
+export interface CredentialBranding {
+  providerId?: string;
+  icon: string;
+  providerLabel: string | null;
+}
+
+function toTitleCase(value: string): string {
+  return value.replace(/_/g, ' ').replace(/\b\w/g, (char) => char.toUpperCase());
+}
+
+function getConfiguredProvider(credential: Credential): string | null {
+  const provider =
+    (credential.config?.oauth2Provider as string | undefined) ??
+    (credential.metadata?.provider as string | undefined) ??
+    (credential.config?.provider as string | undefined) ??
+    null;
+
+  return provider?.trim() || null;
+}
+
+function getProviderFromUrls(credential: Credential): { providerId: string; icon: string } | null {
+  const urlCandidates = [
+    credential.config?.apiUrl,
+    credential.config?.baseUrl,
+    credential.config?.endpoint,
+    credential.metadata?.apiUrl,
+  ];
+
+  for (const candidate of urlCandidates) {
+    if (typeof candidate !== 'string' || candidate.length === 0) {
+      continue;
+    }
+
+    for (const [pattern, providerId, icon] of URL_HINTS) {
+      if (pattern.test(candidate)) {
+        return { providerId, icon };
+      }
+    }
+  }
+
+  return null;
+}
+
+export function getCredentialBranding(credential: Credential): CredentialBranding {
+  const configuredProvider = getConfiguredProvider(credential);
+  if (configuredProvider) {
+    const providerId = OAUTH2_TO_ICON_ID[configuredProvider] ?? configuredProvider.toLowerCase();
+    return {
+      providerId,
+      icon: credential.authType === 'oauth2' ? 'Key' : credential.type === 'llm' ? 'Bot' : 'Key',
+      providerLabel: toTitleCase(configuredProvider),
+    };
+  }
+
+  for (const [pattern, providerId, icon] of NAME_HINTS) {
+    if (pattern.test(credential.name)) {
+      return {
+        providerId,
+        icon,
+        providerLabel: toTitleCase(providerId),
+      };
+    }
+  }
+
+  const urlProvider = getProviderFromUrls(credential);
+  if (urlProvider) {
+    return {
+      providerId: urlProvider.providerId,
+      icon: urlProvider.icon,
+      providerLabel: toTitleCase(urlProvider.providerId),
+    };
+  }
+
+  if (credential.type === 'database') {
+    return { icon: 'Database', providerLabel: null };
+  }
+  if (credential.type === 'llm') {
+    return { icon: 'Bot', providerLabel: null };
+  }
+
+  return { icon: 'Key', providerLabel: null };
+}
+
+export function getCredentialProviderLabel(credential: Credential): string | null {
+  return getCredentialBranding(credential).providerLabel;
+}

package/src/utils/credentialFiltering.ts

@@ -0,0 +1,68 @@
+import type { Credential } from '../api/types';
+
+interface CredentialFieldHints {
+  /** OAuth2 provider IDs to match (e.g., ["google"]) */
+  oauth2Providers?: string[];
+  /** Credential types to match (e.g., ["oauth2", "api_key"]) */
+  credentialTypes?: string[];
+}
+
+/**
+ * Filter a list of credentials to those relevant for a specific credential field.
+ *
+ * Matching rules:
+ * 1. If the field specifies `oauth2Providers`, show credentials whose
+ *    `metadata.oauth2Provider` matches **plus** any non-OAuth2 credentials
+ *    (apiKey, bearer, etc.) that could serve as manual API key fallbacks.
+ * 2. If the field specifies `credentialTypes` (without oauth2Providers),
+ *    filter by `authType`.
+ * 3. If neither is specified, return all credentials (no filtering).
+ */
+export function filterCredentialsForField(
+  credentials: Credential[],
+  field: CredentialFieldHints,
+): Credential[] {
+  // No filtering hints → show everything
+  if (
+    (!field.oauth2Providers || field.oauth2Providers.length === 0) &&
+    (!field.credentialTypes || field.credentialTypes.length === 0)
+  ) {
+    return credentials;
+  }
+
+  // OAuth2 provider filtering (primary case for integration nodes)
+  if (field.oauth2Providers && field.oauth2Providers.length > 0) {
+    const providers = field.oauth2Providers;
+    return credentials.filter((cred) => {
+      // Match by OAuth2 provider stored in metadata or config
+      const credProvider =
+        (cred.metadata?.oauth2Provider as string | undefined) ??
+        (cred.config?.oauth2Provider as string | undefined) ??
+        (cred.metadata?.provider as string | undefined);
+      if (credProvider && providers.includes(credProvider)) {
+        return true;
+      }
+
+      // Also include non-OAuth2 credentials (manual API keys, bearer tokens)
+      // as they might be custom credentials for the same service
+      if (cred.authType !== 'oauth2') {
+        return true;
+      }
+
+      // Exclude OAuth2 credentials from other providers
+      return false;
+    });
+  }
+
+  // Credential type filtering (e.g., ["llm"], ["database"], ["api_key"])
+  // Checks both the credential's `type` (CredentialType: 'llm', 'http-api', 'database')
+  // and `authType` (CredentialAuthType: 'apiKey', 'bearer', 'oauth2', etc.)
+  if (field.credentialTypes && field.credentialTypes.length > 0) {
+    const types = field.credentialTypes;
+    return credentials.filter((cred) => {
+      return types.includes(cred.type) || types.includes(cred.authType);
+    });
+  }
+
+  return credentials;
+}