@inkeep/agents-manage-ui 0.1.0

package/src/hooks/use-traces-query-state.ts

@@ -0,0 +1,88 @@
+import { parseAsJson, parseAsString, parseAsStringLiteral, useQueryStates } from 'nuqs';
+
+// Define the time range options as a const assertion for type safety
+const timeRanges = ['24h', '7d', '15d', 'custom'] as const;
+export type TimeRange = (typeof timeRanges)[number];
+
+// Type for span attributes
+export interface SpanAttribute {
+  key: string;
+  value: string;
+  operator?:
+    | '='
+    | '!='
+    | '<'
+    | '>'
+    | '<='
+    | '>='
+    | 'in'
+    | 'nin'
+    | 'contains'
+    | 'ncontains'
+    | 'regex'
+    | 'nregex'
+    | 'like'
+    | 'nlike'
+    | 'exists'
+    | 'nexists';
+}
+
+/**
+ * Hook for managing traces overview query state with nuqs
+ * Provides type-safe query parameter management for:
+ * - Time range selection (24h, 7d, 15d, custom)
+ * - Custom date range (start/end dates)
+ * - Span filtering (name and attributes)
+ */
+export function useTracesQueryState() {
+  const [queryState, setQueryState] = useQueryStates({
+    // Time range selection with default
+    timeRange: parseAsStringLiteral(timeRanges).withDefault('15d'),
+
+    // Custom date range - using descriptive names
+    customStartDate: parseAsString.withDefault(''),
+    customEndDate: parseAsString.withDefault(''),
+
+    // Span filtering
+    spanName: parseAsString.withDefault(''),
+    spanAttributes: parseAsJson((value: unknown): SpanAttribute[] => {
+      // Validate that the parsed JSON is an array of SpanAttribute objects
+      if (!Array.isArray(value)) return [];
+
+      return value.filter(
+        (item): item is SpanAttribute =>
+          typeof item === 'object' &&
+          item !== null &&
+          typeof (item as any).key === 'string' &&
+          typeof (item as any).value === 'string'
+      );
+    }).withDefault([]),
+  });
+
+  return {
+    // Current state
+    timeRange: queryState.timeRange,
+    customStartDate: queryState.customStartDate,
+    customEndDate: queryState.customEndDate,
+    spanName: queryState.spanName,
+    spanAttributes: queryState.spanAttributes,
+
+    // State setters
+    setQueryState,
+
+    // Convenience methods
+    setTimeRange: (timeRange: TimeRange) => setQueryState({ timeRange }),
+    setCustomDateRange: (start: string, end: string) =>
+      setQueryState({ customStartDate: start, customEndDate: end }),
+    setSpanFilter: (name: string, attributes: SpanAttribute[] = []) =>
+      setQueryState({ spanName: name, spanAttributes: attributes }),
+    clearFilters: () =>
+      setQueryState({
+        spanName: '',
+        spanAttributes: [],
+        timeRange: '15d',
+        customStartDate: '',
+        customEndDate: '',
+      }),
+  };
+}

package/src/hooks/use-traces.ts

@@ -0,0 +1,240 @@
+'use client';
+
+import { useCallback, useEffect, useState } from 'react';
+import {
+  type ConversationStats,
+  getSigNozStatsClient,
+  type PaginatedConversationStats,
+  type SpanFilterOptions,
+} from '@/lib/api/signoz-stats';
+
+const MILLISECONDS_PER_DAY = 24 * 60 * 60 * 1000;
+
+export interface UseConversationStatsResult {
+  stats: ConversationStats[];
+  loading: boolean;
+  error: string | null;
+  refresh: () => void;
+  pagination?: {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    nextPage: () => void;
+    previousPage: () => void;
+    goToPage: (page: number) => void;
+  };
+}
+
+export interface UseConversationStatsOptions {
+  startTime?: number;
+  endTime?: number;
+  filters?: SpanFilterOptions;
+  projectId?: string;
+  pagination?: {
+    enabled: boolean;
+    pageSize?: number;
+  };
+  searchQuery?: string;
+}
+
+export function useConversationStats(
+  options?: UseConversationStatsOptions
+): UseConversationStatsResult {
+  const [stats, setStats] = useState<ConversationStats[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [currentPage, setCurrentPage] = useState(1);
+  const [paginationInfo, setPaginationInfo] = useState<
+    PaginatedConversationStats['pagination'] | null
+  >(null);
+
+  // Extract stable values to avoid object recreation issues
+  const paginationEnabled = options?.pagination?.enabled;
+  const pageSize = options?.pagination?.pageSize || 50;
+
+  const fetchData = useCallback(
+    async (page: number = currentPage) => {
+      try {
+        setLoading(true);
+        setError(null);
+
+        const client = getSigNozStatsClient();
+        // Use provided time range or default to all time (2020)
+        // Clamp endTime to now-1ms to satisfy backend validation (end cannot be in the future)
+        const currentEndTime = Math.min(options?.endTime || Date.now() - 1);
+        const currentStartTime = options?.startTime || new Date('2020-01-01T00:00:00Z').getTime();
+
+        const paginationParams = paginationEnabled ? { page, limit: pageSize } : undefined;
+
+        const result = await client.getConversationStats(
+          currentStartTime,
+          currentEndTime,
+          options?.filters,
+          options?.projectId,
+          paginationParams,
+          options?.searchQuery
+        );
+
+        if (paginationEnabled && typeof result === 'object' && 'data' in result) {
+          // Paginated result
+          setStats(result.data);
+          setPaginationInfo(result.pagination);
+          // Don't set currentPage here to avoid infinite loops - it should be managed by navigation functions
+        } else {
+          // Non-paginated result (backward compatibility)
+          setStats(result as ConversationStats[]);
+          setPaginationInfo(null);
+        }
+      } catch (err) {
+        console.error('Error fetching conversation stats:', err);
+        const errorMessage =
+          err instanceof Error ? err.message : 'Failed to fetch conversation stats';
+        setError(errorMessage);
+      } finally {
+        setLoading(false);
+      }
+    },
+    [
+      options?.startTime,
+      options?.endTime,
+      options?.filters,
+      options?.projectId,
+      options?.searchQuery,
+      paginationEnabled,
+      pageSize,
+    ]
+  ); // Use stable values instead of options object
+
+  const refresh = useCallback(() => {
+    fetchData(currentPage);
+  }, [fetchData, currentPage]);
+
+  // Pagination controls
+  const nextPage = useCallback(() => {
+    if (paginationInfo?.hasNextPage) {
+      const nextPageNum = currentPage + 1;
+      setCurrentPage(nextPageNum);
+      fetchData(nextPageNum);
+    }
+  }, [currentPage, paginationInfo?.hasNextPage, fetchData]);
+
+  const previousPage = useCallback(() => {
+    if (paginationInfo?.hasPreviousPage) {
+      const prevPageNum = currentPage - 1;
+      setCurrentPage(prevPageNum);
+      fetchData(prevPageNum);
+    }
+  }, [currentPage, paginationInfo?.hasPreviousPage, fetchData]);
+
+  const goToPage = useCallback(
+    (page: number) => {
+      if (
+        paginationInfo &&
+        page >= 1 &&
+        page <= paginationInfo.totalPages &&
+        page !== currentPage
+      ) {
+        setCurrentPage(page);
+        fetchData(page);
+      }
+    },
+    [currentPage, paginationInfo, fetchData]
+  );
+
+  // Fetch when component mounts or time range changes
+  useEffect(() => {
+    fetchData();
+  }, [fetchData]);
+
+  // Reset to page 1 when filters or time range change
+  useEffect(() => {
+    if (paginationEnabled) {
+      setCurrentPage(1);
+    }
+  }, [
+    options?.startTime,
+    options?.endTime,
+    options?.filters,
+    options?.projectId,
+    options?.searchQuery,
+    paginationEnabled,
+  ]);
+
+  return {
+    stats,
+    loading,
+    error,
+    refresh,
+    pagination: paginationInfo
+      ? {
+          page: paginationInfo.page,
+          limit: paginationInfo.limit,
+          total: paginationInfo.total,
+          totalPages: paginationInfo.totalPages,
+          hasNextPage: paginationInfo.hasNextPage,
+          hasPreviousPage: paginationInfo.hasPreviousPage,
+          nextPage,
+          previousPage,
+          goToPage,
+        }
+      : undefined,
+  };
+}
+
+// Hook for aggregate stats only (server-side aggregation)
+export function useAggregateStats(options?: {
+  startTime?: number;
+  endTime?: number;
+  filters?: SpanFilterOptions;
+  projectId?: string;
+}) {
+  const [aggregateStats, setAggregateStats] = useState({
+    totalToolCalls: 0,
+    totalTransfers: 0,
+    totalDelegations: 0,
+    totalConversations: 0,
+    totalAICalls: 0,
+  });
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  const fetchAggregateStats = useCallback(async () => {
+    try {
+      setLoading(true);
+      setError(null);
+
+      const client = getSigNozStatsClient();
+      const currentEndTime = Math.min(options?.endTime || Date.now() - 1);
+      const currentStartTime = options?.startTime || new Date('2020-01-01T00:00:00Z').getTime();
+
+      const stats = await client.getAggregateStats(
+        currentStartTime,
+        currentEndTime,
+        options?.filters,
+        options?.projectId
+      );
+
+      setAggregateStats(stats);
+    } catch (err) {
+      console.error('Error fetching aggregate stats:', err);
+      const errorMessage = err instanceof Error ? err.message : 'Failed to fetch aggregate stats';
+      setError(errorMessage);
+    } finally {
+      setLoading(false);
+    }
+  }, [options?.startTime, options?.endTime, options?.filters, options?.projectId]);
+
+  useEffect(() => {
+    fetchAggregateStats();
+  }, [fetchAggregateStats]);
+
+  return {
+    aggregateStats,
+    loading,
+    error,
+    refresh: fetchAggregateStats,
+  };
+}

package/src/lib/README.md

@@ -0,0 +1,145 @@
+# Agent Builder Library
+
+This library provides server actions and types for interacting with the GraphFull API from the inkeep-chat backend. It imports the original schemas from the inkeep-chat package to avoid duplication and ensure consistency.
+
+## Configuration
+
+Set the following environment variable in your `.env.local` file:
+
+```bash
+NEXT_PUBLIC_INKEEP_CHAT_API_URL="http://localhost:3002"
+```
+
+## Usage
+
+### Import the server actions and types
+
+```typescript
+import {
+  createFullGraphAction,
+  getFullGraphAction,
+  updateFullGraphAction,
+  deleteFullGraphAction,
+  validateGraphData,
+  FullGraphDefinitionSchema,
+  type FullGraphDefinition,
+  type ActionResult,
+} from '@/lib';
+```
+
+### Create a new graph
+
+```typescript
+const result = await createFullGraphAction('tenant-123', {
+  id: 'my-graph',
+  name: 'My Customer Service Graph',
+  description: 'A graph for customer service operations',
+  defaultAgentId: 'support-agent',
+  agents: {
+    'support-agent': {
+      id: 'support-agent',
+      name: 'Support Agent',
+      description: 'Handles customer support',
+      tools: ['email-tool'],
+    }
+  },
+  tools: {
+    'email-tool': {
+      id: 'email-tool',
+      name: 'Email Tool',
+      type: 'mcp',
+      config: {}
+    }
+  }
+});
+
+if (result.success) {
+  console.log('Graph created:', result.data);
+} else {
+  console.error('Error:', result.error);
+}
+```
+
+### Get an existing graph
+
+```typescript
+const result = await getFullGraphAction('tenant-123', 'my-graph');
+
+if (result.success) {
+  console.log('Graph retrieved:', result.data);
+} else {
+  console.error('Error:', result.error);
+}
+```
+
+### Update a graph
+
+```typescript
+const updatedGraph = {
+  id: 'my-graph',
+  name: 'Updated Customer Service Graph',
+  // ... other properties
+};
+
+const result = await updateFullGraphAction('tenant-123', 'my-graph', updatedGraph);
+
+if (result.success) {
+  console.log('Graph updated:', result.data);
+} else {
+  console.error('Error:', result.error);
+}
+```
+
+### Delete a graph
+
+```typescript
+const result = await deleteFullGraphAction('tenant-123', 'my-graph');
+
+if (result.success) {
+  console.log('Graph deleted successfully');
+} else {
+  console.error('Error:', result.error);
+}
+```
+
+### Validate graph data
+
+Use this for form validation before submitting:
+
+```typescript
+const result = await validateGraphData(formData);
+
+if (result.success) {
+  // Data is valid, proceed with submission
+  const validatedData = result.data;
+} else {
+  // Show validation errors
+  console.error('Validation error:', result.error);
+}
+```
+
+## Type Safety
+
+All functions return an `ActionResult<T>` type that ensures proper error handling:
+
+```typescript
+type ActionResult<T = void> = {
+  success: true;
+  data: T;
+} | {
+  success: false;
+  error: string;
+  code?: string;
+};
+```
+
+## Error Codes
+
+The API may return the following error codes:
+
+- `not_found`: Graph not found
+- `bad_request`: Invalid request data
+- `internal_server_error`: Server error
+- `conflict`: Graph already exists (on create)
+- `validation_error`: Client-side validation failed
+- `unknown_error`: Unexpected error occurred

package/src/lib/actions/api-keys.ts

@@ -0,0 +1,99 @@
+'use server';
+
+import { revalidatePath } from 'next/cache';
+import {
+  type ApiKey,
+  type ApiKeyCreateResponse,
+  createApiKey,
+  deleteApiKey,
+  fetchApiKeys,
+} from '../api/api-keys';
+import { ApiError } from '../types/errors';
+import type { ActionResult } from './types';
+
+/**
+ * Fetch all API keys
+ */
+export async function fetchApiKeysAction(
+  tenantId: string,
+  projectId: string
+): Promise<ActionResult<ApiKey[]>> {
+  try {
+    const result = await fetchApiKeys(tenantId, projectId);
+    return {
+      success: true,
+      data: result.data,
+    };
+  } catch (error) {
+    if (error instanceof ApiError) {
+      return {
+        success: false,
+        error: error.message,
+        code: error.error.code,
+      };
+    }
+
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Unknown error occurred',
+      code: 'unknown_error',
+    };
+  }
+}
+
+export async function createApiKeyAction(
+  tenantId: string,
+  projectId: string,
+  apiKeyData: Partial<ApiKey>
+): Promise<ActionResult<ApiKeyCreateResponse>> {
+  try {
+    const result = await createApiKey(tenantId, projectId, apiKeyData);
+    revalidatePath(`/${tenantId}/projects/${projectId}/api-keys`);
+    return {
+      success: true,
+      data: result,
+    };
+  } catch (error) {
+    if (error instanceof ApiError) {
+      return {
+        success: false,
+        error: error.message,
+        code: error.error.code,
+      };
+    }
+
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Unknown error occurred',
+      code: 'unknown_error',
+    };
+  }
+}
+
+export async function deleteApiKeyAction(
+  tenantId: string,
+  projectId: string,
+  apiKeyId: string
+): Promise<ActionResult<void>> {
+  try {
+    await deleteApiKey(tenantId, projectId, apiKeyId);
+    revalidatePath(`/${tenantId}/projects/${projectId}/api-keys`);
+    return {
+      success: true,
+    };
+  } catch (error) {
+    if (error instanceof ApiError) {
+      return {
+        success: false,
+        error: error.message,
+        code: error.error.code,
+      };
+    }
+
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Unknown error occurred',
+      code: 'unknown_error',
+    };
+  }
+}

package/src/lib/actions/artifact-components.ts

@@ -0,0 +1,143 @@
+/**
+ * Server actions for artifact components operations with path revalidation
+ */
+
+'use server';
+
+import { revalidatePath } from 'next/cache';
+import type { ArtifactComponent } from '../api/artifact-components';
+import {
+  createArtifactComponent,
+  deleteArtifactComponent,
+  fetchArtifactComponents,
+  updateArtifactComponent,
+} from '../api/artifact-components';
+import { ApiError } from '../types/errors';
+import type { ActionResult } from './types';
+
+/**
+ * Fetch all data components
+ */
+export async function fetchArtifactComponentsAction(
+  tenantId: string,
+  projectId: string
+): Promise<ActionResult<ArtifactComponent[]>> {
+  try {
+    const result = await fetchArtifactComponents(tenantId, projectId);
+    return {
+      success: true,
+      data: result.data,
+    };
+  } catch (error) {
+    if (error instanceof ApiError) {
+      return {
+        success: false,
+        error: error.message,
+        code: error.error.code,
+      };
+    }
+
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Unknown error occurred',
+      code: 'unknown_error',
+    };
+  }
+}
+
+/**
+ * Create a new artifact component
+ */
+export async function createArtifactComponentAction(
+  tenantId: string,
+  projectId: string,
+  data: ArtifactComponent
+): Promise<ActionResult<ArtifactComponent>> {
+  try {
+    const result = await createArtifactComponent(tenantId, projectId, data);
+    revalidatePath(`/${tenantId}/projects/${projectId}/artifact-components`);
+    return {
+      success: true,
+      data: result,
+    };
+  } catch (error) {
+    if (error instanceof ApiError) {
+      return {
+        success: false,
+        error: error.message,
+        code: error.error.code,
+      };
+    }
+
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Unknown error occurred',
+      code: 'unknown_error',
+    };
+  }
+}
+
+/**
+ * Update an existing artifact component
+ */
+export async function updateArtifactComponentAction(
+  tenantId: string,
+  projectId: string,
+  data: ArtifactComponent
+): Promise<ActionResult<ArtifactComponent>> {
+  try {
+    const result = await updateArtifactComponent(tenantId, projectId, data);
+    revalidatePath(`/${tenantId}/projects/${projectId}/artifact-components`);
+    revalidatePath(`/${tenantId}/projects/${projectId}/artifact-components/${data.id}`);
+    return {
+      success: true,
+      data: result,
+    };
+  } catch (error) {
+    if (error instanceof ApiError) {
+      return {
+        success: false,
+        error: error.message,
+        code: error.error.code,
+      };
+    }
+
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Unknown error occurred',
+      code: 'unknown_error',
+    };
+  }
+}
+
+/**
+ * Delete an artifact component
+ */
+export async function deleteArtifactComponentAction(
+  tenantId: string,
+  projectId: string,
+  artifactComponentId: string
+): Promise<ActionResult<void>> {
+  try {
+    await deleteArtifactComponent(tenantId, projectId, artifactComponentId);
+    revalidatePath(`/${tenantId}/projects/${projectId}/artifact-components`);
+    revalidatePath(`/${tenantId}/projects/${projectId}/artifact-components/${artifactComponentId}`);
+    return {
+      success: true,
+    };
+  } catch (error) {
+    if (error instanceof ApiError) {
+      return {
+        success: false,
+        error: error.message,
+        code: error.error.code,
+      };
+    }
+
+    return {
+      success: false,
+      error: error instanceof Error ? error.message : 'Unknown error occurred',
+      code: 'unknown_error',
+    };
+  }
+}