@app-studio/web 0.9.18 → 0.9.20

package/docs/api-integration.md

@@ -0,0 +1,801 @@
+# API Integration Guide
+
+This guide explains how to integrate with backend APIs in the Front-Starter project. The project uses OpenAPI-generated services for type-safe API calls.
+
+## API Service Structure
+
+API services are generated from OpenAPI/Swagger specifications and stored in the `src/services/api` directory. These services provide type-safe methods for interacting with the backend API.
+
+Each service in the `src/services/api` directory contains:
+
+1. **Base API functions** - Direct functions that return CancelablePromise objects
+2. **Generated hooks** - React hooks that wrap the base functions with the `useRequest` hook from `@app-studio/react-request`
+
+For example, a typical service like `UserService` contains functions like:
+
+```typescript
+// Base API function
+export const userControllerRead = (id: string): CancelablePromise<any> => {
+  return __request({
+    method: 'GET',
+    path: `/users/${id}`,
+    errors: {
+      404: `User not found`,
+    },
+  });
+};
+
+// Generated hook that wraps the base function
+export const useUserControllerReadService = ({ method = 'GET', ...options }: UseRequestOption = {}): {
+  run: (id: string) => void;
+  data: any;
+} & UseRequestProperties => {
+  return useRequest(userControllerRead, { method, ...options });
+};
+```
+
+These generated hooks provide a consistent interface for making API requests with built-in loading, error, and success states.
+
+## Generating API Services
+
+The project includes scripts to generate API services from OpenAPI/Swagger specifications:
+
+```bash
+# Generate API services from local Swagger docs
+npm run api:local
+# or
+yarn api:local
+
+# Generate API services from remote Swagger docs
+npm run api
+# or
+yarn api
+```
+
+These scripts generate TypeScript files in the `src/services/api` directory based on the API specification.
+
+### How API Services Are Generated
+
+The API services are automatically generated using the `react-api` tool with the following command:
+
+```bash
+react-api --useUnionTypes --input http://localhost:3000/docs/swagger.json --output ./src/services/api && prettier --write ./src/services/api
+```
+
+This command:
+1. Uses the `react-api` tool from the `@app-studio/react-api` package
+2. Enables union types with the `--useUnionTypes` flag for better TypeScript type safety
+3. Reads the OpenAPI/Swagger specification from `http://localhost:3000/docs/swagger.json`
+4. Outputs the generated TypeScript files to the `./src/services/api` directory
+5. Formats the generated code with Prettier
+
+The generated services include both the base API functions and React hooks that wrap these functions with the `useRequest` hook from `@app-studio/react-request`.
+
+## API Configuration
+
+The API base URL is configured in `src/configs/AppConfig.ts`:
+
+```typescript
+export const API_URL = env.REACT_APP_API_URL ? env.REACT_APP_API_URL : 'http://localhost:3000';
+```
+
+The OpenAPI configuration is set up in `src/utils/request.ts`:
+
+```typescript
+import { OpenAPI } from 'src/services/api';
+
+// Set the base URL for API requests
+OpenAPI.BASE = API_URL;
+OpenAPI.CORS = 'cors';
+```
+
+## Authentication
+
+Authentication tokens are managed in the `AuthStore` and set in the OpenAPI configuration:
+
+```typescript
+// Set the authentication token for API requests
+export async function setToken(token: string) {
+  access_token = token;
+  OpenAPI.TOKEN = token;
+}
+```
+
+### Using Auth Hooks
+
+The project provides several authentication-related hooks in the API services:
+
+```typescript
+// Login example
+import { AuthService } from 'src/services/api';
+import { useAuthStore } from 'src/stores/AuthStore';
+
+const LoginForm = () => {
+  const { setUser, setToken } = useAuthStore();
+
+  const loginRequest = AuthService.useAuthControllerLoginService({
+    onSuccess: (data) => {
+      // Store the token and user data
+      setToken(data.token);
+      setUser(data.user);
+
+      // Redirect to dashboard
+      navigate('/dashboard');
+    },
+    onError: (error) => {
+      showToast('error', 'Login Failed', error.message);
+    },
+  });
+
+  const handleSubmit = (values) => {
+    loginRequest.run({
+      email: values.email,
+      password: values.password,
+    });
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {/* Form fields */}
+    </form>
+  );
+};
+```
+
+### Handling Expired Tokens
+
+To handle expired tokens, you can set up a global error handler in the request configuration:
+
+```typescript
+// In src/utils/request.ts
+import { OpenAPI, ApiError } from 'src/services/api';
+import { useAuthStore } from 'src/stores/AuthStore';
+
+// Set up global error handler
+const originalFetch = window.fetch;
+window.fetch = async (...args) => {
+  try {
+    const response = await originalFetch(...args);
+
+    // Handle 401 Unauthorized errors
+    if (response.status === 401) {
+      const { logout } = useAuthStore.getState();
+      logout();
+      window.location.href = '/login?expired=true';
+    }
+
+    return response;
+  } catch (error) {
+    console.error('API request failed:', error);
+    throw error;
+  }
+};
+```
+
+## Making API Requests
+
+### Request Hooks
+
+The recommended way to make API requests is to create request hooks in `.request.ts` files. These hooks wrap the API services and provide loading, error, and success states.
+
+#### Using Generated Hooks
+
+The simplest approach is to use the generated hooks directly from the API services:
+
+```typescript
+// example.component.tsx
+import { UserService } from 'src/services/api';
+
+export const UserProfile = ({ userId }) => {
+  const getUserRequest = UserService.useUserControllerReadService({
+    onSuccess: (data) => {
+      console.log('User data fetched:', data);
+    },
+    onError: (error) => {
+      console.error('Error fetching user:', error);
+    },
+  });
+
+  useEffect(() => {
+    getUserRequest.run(userId);
+  }, [userId]);
+
+  return (
+    <div>
+      {getUserRequest.loading ? (
+        <p>Loading...</p>
+      ) : getUserRequest.data ? (
+        <div>
+          <h2>{getUserRequest.data.name}</h2>
+          <p>{getUserRequest.data.email}</p>
+        </div>
+      ) : null}
+    </div>
+  );
+};
+```
+
+#### Creating Custom Request Hooks
+
+For more complex scenarios, create custom request hooks in `.request.ts` files that combine multiple API services:
+
+```typescript
+// example.request.ts
+import { useRequest } from '@app-studio/react-request';
+import { ExampleService } from 'src/services/api';
+
+export const useExampleRequests = (callbacks = {}) => {
+  const fetchDataRequest = useRequest({
+    request: ExampleService.exampleControllerFindAll,
+    onSuccess: callbacks.onFetchDataSuccess,
+    onError: callbacks.onFetchDataError,
+    onFetch: (params) => {
+      // This runs when the request is made
+      console.log('Fetching data with params:', params);
+    },
+  });
+
+  const createItemRequest = useRequest({
+    request: ExampleService.exampleControllerCreate,
+    onSuccess: (data) => {
+      // You can refresh the data list after creating a new item
+      fetchDataRequest.run();
+
+      // And call the provided callback
+      if (callbacks.onCreateItemSuccess) {
+        callbacks.onCreateItemSuccess(data);
+      }
+    },
+    onError: callbacks.onCreateItemError,
+  });
+
+  return {
+    fetchDataRequest,
+    createItemRequest,
+  };
+};
+```
+
+#### useRequest Options
+
+The `useRequest` hook and the generated service hooks accept several options:
+
+- `method`: HTTP method to use (GET, POST, etc.)
+- `onSuccess`: Callback function that runs when the request succeeds
+- `onError`: Callback function that runs when the request fails
+- `onFetch`: Callback function that runs when the request is made
+- `initialData`: Initial data to use before the request completes
+- `manual`: Whether to run the request manually (default: true)
+- `debounce`: Debounce time in milliseconds
+- `throttle`: Throttle time in milliseconds
+
+### Using Request Hooks in Components
+
+Request hooks can be used in components to make API calls and handle responses:
+
+```typescript
+// example.component.tsx
+import React, { useEffect } from 'react';
+import { useExampleRequests } from './example.request';
+
+export const ExampleComponent = () => {
+  const { fetchDataRequest, createItemRequest } = useExampleRequests({
+    onFetchDataSuccess: (data) => {
+      console.log('Data fetched successfully:', data);
+    },
+    onFetchDataError: (error) => {
+      console.error('Error fetching data:', error);
+    },
+  });
+
+  useEffect(() => {
+    // Fetch data when the component mounts
+    fetchDataRequest.run();
+  }, []);
+
+  const handleCreateItem = () => {
+    createItemRequest.run({
+      name: 'New Item',
+      description: 'This is a new item',
+    });
+  };
+
+  return (
+    <div>
+      {fetchDataRequest.loading ? (
+        <p>Loading...</p>
+      ) : fetchDataRequest.error ? (
+        <p>Error: {fetchDataRequest.error.message}</p>
+      ) : (
+        <ul>
+          {fetchDataRequest.data?.map((item) => (
+            <li key={item.id}>{item.name}</li>
+          ))}
+        </ul>
+      )}
+
+      <button onClick={handleCreateItem} disabled={createItemRequest.loading}>
+        Create Item
+      </button>
+    </div>
+  );
+};
+```
+
+## Error Handling
+
+Error handling is an important part of API integration. The request hooks provide error states that can be used to display error messages to the user.
+
+### Basic Error Handling
+
+```typescript
+// Error handling in a component
+if (fetchDataRequest.error) {
+  return (
+    <div>
+      <p>Error: {fetchDataRequest.error.message}</p>
+      <button onClick={() => fetchDataRequest.run()}>Retry</button>
+    </div>
+  );
+}
+```
+
+### Using showToast for User Feedback
+
+You can use the `showToast` function from `@app-studio/web` to display error messages:
+
+```typescript
+import { showToast } from '@app-studio/web';
+
+// In the onError callback
+onError: (error) => {
+  showToast('error', 'Error', error.message || 'An error occurred');
+}
+```
+
+### Centralized Error Handling
+
+For consistent error handling across your application, create a centralized error handler:
+
+```typescript
+// utils/errorHandler.ts
+import { showToast } from '@app-studio/web';
+import { ApiError } from 'src/services/api';
+
+export const handleApiError = (error: any, title = 'Error') => {
+  if (error instanceof ApiError) {
+    // Handle specific API error codes
+    switch (error.status) {
+      case 400:
+        showToast('error', title, 'Invalid request. Please check your input.');
+        break;
+      case 401:
+        showToast('error', title, 'Authentication required. Please log in again.');
+        // Redirect to login page
+        window.location.href = '/login';
+        break;
+      case 403:
+        showToast('error', title, 'You do not have permission to perform this action.');
+        break;
+      case 404:
+        showToast('error', title, 'The requested resource was not found.');
+        break;
+      case 500:
+        showToast('error', title, 'Server error. Please try again later.');
+        break;
+      default:
+        showToast('error', title, error.message || 'An unexpected error occurred.');
+    }
+  } else {
+    // Handle non-API errors
+    showToast('error', title, error.message || 'An unexpected error occurred.');
+  }
+
+  // Log the error for debugging
+  console.error('API Error:', error);
+};
+
+// Using the centralized error handler in your request hooks
+const fetchDataRequest = useRequest({
+  request: ExampleService.exampleControllerFindAll,
+  onSuccess: (data) => {
+    // Handle success
+  },
+  onError: (error) => {
+    handleApiError(error, 'Data Fetch Failed');
+  },
+});
+```
+
+### Error Boundaries for React Components
+
+Use React Error Boundaries to catch and handle errors in your components:
+
+```typescript
+// components/ErrorBoundary.tsx
+import React, { Component, ErrorInfo, ReactNode } from 'react';
+
+interface Props {
+  children: ReactNode;
+  fallback?: ReactNode;
+}
+
+interface State {
+  hasError: boolean;
+  error?: Error;
+}
+
+class ErrorBoundary extends Component<Props, State> {
+  constructor(props: Props) {
+    super(props);
+    this.state = { hasError: false };
+  }
+
+  static getDerivedStateFromError(error: Error): State {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo): void {
+    console.error('Component error:', error, errorInfo);
+  }
+
+  render(): ReactNode {
+    if (this.state.hasError) {
+      return this.props.fallback || (
+        <div>
+          <h2>Something went wrong.</h2>
+          <p>{this.state.error?.message}</p>
+          <button onClick={() => this.setState({ hasError: false })}>Try again</button>
+        </div>
+      );
+    }
+
+    return this.props.children;
+  }
+}
+
+// Using the error boundary in your components
+const DataComponent = () => (
+  <ErrorBoundary>
+    <UserList />
+  </ErrorBoundary>
+);
+```
+
+## Pagination and Filtering
+
+For paginated API endpoints, you can pass pagination parameters to the request:
+
+```typescript
+// Fetch paginated data
+fetchDataRequest.run({
+  take: 10,
+  skip: (currentPage - 1) * 10,
+  filter: searchTerm,
+  sortBy: 'createdAt',
+  sortOrder: 'desc',
+});
+```
+
+## Caching and Data Persistence
+
+The request hooks do not include built-in caching. If you need to cache API responses, you can store the data in a Zustand store:
+
+```typescript
+// stores/DataStore.ts
+import { create } from 'zustand';
+
+interface DataState {
+  items: any[];
+  setItems: (items: any[]) => void;
+  isLoading: boolean;
+  setLoading: (isLoading: boolean) => void;
+  error: Error | null;
+  setError: (error: Error | null) => void;
+  fetchItems: () => Promise<void>;
+}
+
+export const useDataStore = create<DataState>((set, get) => ({
+  items: [],
+  setItems: (items) => set({ items }),
+  isLoading: false,
+  setLoading: (isLoading) => set({ isLoading }),
+  error: null,
+  setError: (error) => set({ error }),
+
+  // Fetch items from the API
+  fetchItems: async () => {
+    try {
+      set({ isLoading: true, error: null });
+
+      // Import the API service directly in the action
+      const { ExampleService } = await import('src/services/api');
+
+      // Call the API directly (not using hooks in stores)
+      const data = await ExampleService.exampleControllerFindAll();
+
+      set({ items: data, isLoading: false });
+      return data;
+    } catch (error) {
+      set({ error: error as Error, isLoading: false });
+      throw error;
+    }
+  },
+}));
+
+// In your component
+import { useDataStore } from 'src/stores/DataStore';
+import { useEffect } from 'react';
+
+const ExampleComponent = () => {
+  const { items, isLoading, error, fetchItems } = useDataStore();
+
+  useEffect(() => {
+    fetchItems();
+  }, []);
+
+  return (
+    <div>
+      {isLoading ? (
+        <p>Loading...</p>
+      ) : error ? (
+        <p>Error: {error.message}</p>
+      ) : (
+        <ul>
+          {items.map((item) => (
+            <li key={item.id}>{item.name}</li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+};
+```
+
+### Integrating API Hooks with Zustand Stores
+
+For more complex state management, you can combine API hooks with Zustand stores:
+
+```typescript
+// Component using both API hooks and Zustand store
+import { useEffect } from 'react';
+import { UserService } from 'src/services/api';
+import { useDataStore } from 'src/stores/DataStore';
+
+const UserList = () => {
+  // API hook for fetching users
+  const getUsersRequest = UserService.useUserControllerFindService({
+    onSuccess: (data) => {
+      // Update the store with the fetched data
+      setItems(data);
+    },
+  });
+
+  // Zustand store for caching the data
+  const { items, setItems } = useDataStore();
+
+  useEffect(() => {
+    // If we already have cached data, don't fetch again
+    if (items.length === 0) {
+      getUsersRequest.run();
+    }
+  }, []);
+
+  return (
+    <div>
+      {getUsersRequest.loading ? (
+        <p>Loading...</p>
+      ) : getUsersRequest.error ? (
+        <p>Error: {getUsersRequest.error.message}</p>
+      ) : (
+        <ul>
+          {items.map((user) => (
+            <li key={user.id}>{user.name}</li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+};
+```
+
+## File Uploads
+
+For file uploads, you can use the `MediaUploader` component:
+
+```typescript
+import { MediaUploader } from 'src/components/MediaUploader';
+
+<MediaUploader
+  onUpload={(file) => {
+    uploadFileRequest.run({
+      file,
+      type: 'image',
+    });
+  }}
+  accept="image/*"
+/>
+```
+
+## Websockets and Real-time Data
+
+For real-time data, you can use the `multimodalLiveClient` utility:
+
+```typescript
+import { LiveClientSetup } from 'src/lib/multimodalLiveClient';
+
+// Set up a real-time connection
+const client = new LiveClientSetup({
+  url: 'wss://api.example.com/ws',
+  token: authToken,
+});
+
+// Listen for messages
+client.on('message', (message) => {
+  console.log('Received message:', message);
+});
+
+// Send a message
+client.send({
+  type: 'chat',
+  content: 'Hello, world!',
+});
+```
+
+## Advanced API Integration Patterns
+
+### Request Orchestration
+
+For complex pages that require multiple API calls, it's recommended to create a centralized request module like `editor.request.ts`. This approach provides several benefits:
+
+1. **Centralized API logic**: All API calls are defined in one place
+2. **Coordinated data fetching**: Easily chain and coordinate multiple API calls
+3. **Reusable request hooks**: Create custom hooks that can be used across components
+4. **Consistent error handling**: Implement consistent error handling for all API calls
+
+Here's an example based on the pattern used in `src/pages/editor/editor.request.ts`:
+
+```typescript
+// page.request.ts
+import {
+  UserService,
+  ContentService,
+  CommentService
+} from 'src/services/api';
+
+const usePageRequests = ({
+  // Callbacks for different operations
+  getUserCallback = (data) => {},
+  getContentCallback = (data) => {},
+  getCommentsCallback = (data) => {},
+  onError = () => {},
+}) => {
+  // Get user data
+  const getUserRequest = UserService.useUserControllerReadService({
+    onSuccess: (data) => {
+      getUserCallback(data);
+
+      // After getting user data, fetch their content
+      if (data?.id) {
+        getContentRequest.run({ userId: data.id });
+      }
+    },
+    onError,
+  });
+
+  // Get content data
+  const getContentRequest = ContentService.useContentControllerFindService({
+    onSuccess: (data) => {
+      getContentCallback(data);
+
+      // After getting content, fetch comments for each content item
+      if (data?.items?.length) {
+        data.items.forEach(item => {
+          getCommentsRequest.run({ contentId: item.id });
+        });
+      }
+    },
+    onError,
+  });
+
+  // Get comments
+  const getCommentsRequest = CommentService.useCommentControllerFindService({
+    onSuccess: getCommentsCallback,
+    onError,
+  });
+
+  // Create comment
+  const createCommentRequest = CommentService.useCommentControllerCreateService({
+    onSuccess: (data) => {
+      // Refresh comments after creating a new one
+      getCommentsRequest.run({ contentId: data.contentId });
+    },
+    onError,
+  });
+
+  return {
+    getUserRequest,
+    getContentRequest,
+    getCommentsRequest,
+    createCommentRequest,
+  };
+};
+
+export default usePageRequests;
+```
+
+### Composing Multiple API Requests
+
+When working with complex data flows, you often need to chain API requests together. Here are some common patterns:
+
+#### Sequential Requests
+
+Use the `onSuccess` callback to trigger dependent requests:
+
+```typescript
+const getPageRequest = PageService.usePageControllerReadService({
+  onSuccess: (data) => {
+    // Store the page data
+    getPageCallback(data);
+
+    // If the page has a workflow, fetch it
+    if (data?.workflowId) {
+      getWorkflowRequest.run(data.workflowId);
+    }
+  },
+});
+```
+
+#### Refreshing Data After Mutations
+
+After creating, updating, or deleting data, refresh the relevant data:
+
+```typescript
+const deleteComponentRequest = ComponentService.useComponentControllerDeleteService({
+  onSuccess: () => {
+    // Refresh the page data after deleting a component
+    getPageRequest.run(id);
+  },
+});
+```
+
+#### Handling Request Dependencies
+
+When one request depends on the result of another:
+
+```typescript
+// First, get the user
+getUserRequest.run(userId);
+
+// In the onSuccess callback of getUserRequest
+onSuccess: (userData) => {
+  // Then get the user's content
+  getContentRequest.run({ userId: userData.id });
+
+  // In the onSuccess callback of getContentRequest
+  onSuccess: (contentData) => {
+    // Finally, get comments for each content item
+    contentData.items.forEach(item => {
+      getCommentsRequest.run({ contentId: item.id });
+    });
+  }
+}
+```
+
+## Best Practices
+
+1. **Use Generated API Hooks**: Leverage the hooks from `@src/services/api/` for type-safe API calls
+2. **Create Request Modules**: For complex pages, create dedicated `.request.ts` files that orchestrate multiple API calls
+3. **Chain Requests Properly**: Use `onSuccess` callbacks to chain dependent requests
+4. **Handle Loading States**: Always show loading indicators when requests are in progress
+5. **Implement Error Handling**: Use `onError` callbacks to handle errors consistently
+6. **Refresh Data After Mutations**: Update relevant data after create, update, or delete operations
+7. **Use Callbacks for Component Communication**: Pass callback functions to request hooks to communicate with components
+8. **Type Safety**: Use the generated TypeScript types for request parameters and responses
+9. **Pagination**: Implement pagination for large data sets
+10. **Caching**: Consider using Zustand stores to cache frequently accessed data
+11. **Authentication**: Ensure authentication tokens are properly managed in the AuthStore
+12. **Validation**: Validate user input before sending it to the API
+13. **Testing**: Write tests for API integration to ensure it works as expected
+
+By following these guidelines and leveraging the patterns from the codebase, you can create robust and maintainable API integration in your Front-Starter project.