@dev-fastn-ai/react-core 1.0.0

package/README.md

@@ -0,0 +1,1710 @@
+<!-- # @fastn-ai/react-core
+
+A powerful React library for seamlessly integrating the Fastn AI connector marketplace into your applications. This package provides a complete set of hooks and components to manage connectors, configurations, and dynamic forms with full TypeScript support.
+
+## 🚀 Features
+
+- **🔌 Connector Management**: Fetch, display, and manage marketplace connectors
+- **⚙️ Configuration Handling**: Create, update, and manage connector configurations
+- **📝 Dynamic Forms**: Render configuration forms with async field options
+- **🔄 Real-time Updates**: Built-in caching and background refetching
+- **🎨 Customizable**: Full styling control and component customization
+- **📱 TypeScript First**: Complete type safety and IntelliSense support
+- **⚡ Performance Optimized**: React Query powered with intelligent caching
+
+## 📦 Installation
+
+```bash
+npm install @fastn-ai/react-core
+```
+
+### Peer Dependencies
+
+This package requires React 18+ and React Query. Make sure you have these installed:
+
+```bash
+npm install react react-dom @tanstack/react-query
+```
+
+## 🏗️ Quick Start
+
+### 1. Setup the Provider
+
+First, wrap your application with the `FastnProvider` and provide your configuration:
+
+```tsx
+import { FastnProvider } from '@fastn-ai/react-core';
+
+function App() {
+  const fastnConfig = {
+    baseUrl: 'https://api.fastn.ai', // Optional: defaults to production
+    environment: 'LIVE', // 'LIVE' | 'DRAFT' | custom string
+    authToken: 'your-auth-token',
+    tenantId: 'your-tenant-id',
+    spaceId: 'your-space-id',
+    customAuth: false, // Optional: for custom authentication
+  };
+
+  return (
+    <FastnProvider config={fastnConfig}>
+      <YourApp />
+    </FastnProvider>
+  );
+}
+```
+
+### 2. Use the Hooks
+
+Now you can use any of the provided hooks in your components:
+
+```tsx
+import { useConnectors, useConfigurations } from '@fastn-ai/react-core';
+
+function MyComponent() {
+  const { data: connectors, isLoading, error } = useConnectors();
+  
+  if (isLoading) return <div>Loading connectors...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  
+  return (
+    <div>
+      {connectors?.map(connector => (
+        <ConnectorCard key={connector.id} connector={connector} />
+      ))}
+    </div>
+  );
+}
+```
+
+## 📚 Detailed API Reference
+
+### FastnProvider
+
+The main provider component that initializes the Fastn client and provides React Query context.
+
+#### Props
+
+```tsx
+interface FastnProviderProps {
+  children: React.ReactNode;
+  config: Required<FastnConfig>;
+}
+
+interface FastnConfig {
+  baseUrl?: string;
+  environment?: FastnEnvironment;
+  authToken: string;
+  tenantId: string;
+  spaceId: string;
+  customAuth?: boolean;
+}
+
+type FastnEnvironment = 'LIVE' | 'DRAFT' | string;
+```
+
+#### Example
+
+```tsx
+import { FastnProvider } from '@fastn-ai/react-core';
+
+function App() {
+  const config = {
+    baseUrl: 'https://api.fastn.ai',
+    environment: 'LIVE',
+    authToken: process.env.REACT_APP_FASTN_AUTH_TOKEN!,
+    tenantId: process.env.REACT_APP_FASTN_TENANT_ID!,
+    spaceId: process.env.REACT_APP_FASTN_SPACE_ID!,
+    customAuth: false,
+  };
+
+  return (
+    <FastnProvider config={config}>
+      <Router>
+        <Routes>
+          <Route path="/connectors" element={<ConnectorsPage />} />
+          <Route path="/configurations" element={<ConfigurationsPage />} />
+        </Routes>
+      </Router>
+    </FastnProvider>
+  );
+}
+```
+
+### useConnectors
+
+Fetches and manages the list of available connectors from the marketplace.
+
+#### Usage
+
+```tsx
+import { useConnectors } from '@fastn-ai/react-core';
+
+function ConnectorsList() {
+  const { 
+    data: connectors, 
+    isLoading, 
+    error, 
+    refetch 
+  } = useConnectors();
+
+  if (isLoading) return <ConnectorsSkeleton />;
+  if (error) return <ErrorMessage error={error} />;
+
+  return (
+    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
+      {connectors?.map(connector => (
+        <ConnectorCard 
+          key={connector.id} 
+          connector={connector}
+          onRefresh={refetch}
+        />
+      ))}
+    </div>
+  );
+}
+```
+
+#### Return Value
+
+```tsx
+interface UseConnectorsReturn {
+  data: Connector[] | undefined;
+  isLoading: boolean;
+  isError: boolean;
+  error: Error | null;
+  refetch: () => Promise<any>;
+  isFetching: boolean;
+  isSuccess: boolean;
+}
+```
+
+#### Connector Type
+
+```tsx
+interface Connector {
+  readonly id: string;
+  readonly name: string;
+  readonly description: string;
+  readonly imageUri?: string;
+  readonly status: ConnectorStatus;
+  readonly actions: readonly ConnectorAction[];
+}
+
+enum ConnectorStatus {
+  ACTIVE = "ACTIVE",
+  INACTIVE = "INACTIVE",
+  ALL = "ALL",
+}
+
+interface ConnectorAction {
+  readonly name: string;
+  readonly actionType: ConnectorActionType | string;
+  readonly form?: ConnectorForm | null;
+  readonly onClick?: (data?: unknown) => Promise<unknown>;
+  readonly onSubmit?: (formData: Record<string, unknown>) => Promise<unknown>;
+}
+
+enum ConnectorActionType {
+  ACTIVATION = "ACTIVATION",
+  DEACTIVATION = "DEACTIVATION",
+  NONE = "NONE",
+  ENABLE = "ENABLE",
+  DISABLE = "DISABLE",
+  DELETE = "DELETE",
+}
+```
+
+### useConfigurations
+
+Fetches and manages connector configurations for a specific configuration ID.
+
+#### Usage
+
+```tsx
+import { useConfigurations } from '@fastn-ai/react-core';
+
+function ConfigurationsList({ configurationId }: { configurationId: string }) {
+  const { 
+    data: configurations, 
+    isLoading, 
+    error 
+  } = useConfigurations({ 
+    configurationId,
+    status: 'ALL' // 'ENABLED' | 'DISABLED' | 'ALL' | 'IDLE'
+  });
+
+  if (isLoading) return <ConfigurationsSkeleton />;
+  if (error) return <ErrorMessage error={error} />;
+
+  return (
+    <div className="space-y-4">
+      {configurations?.map(configuration => (
+        <ConfigurationCard 
+          key={configuration.id} 
+          configuration={configuration}
+        />
+      ))}
+    </div>
+  );
+}
+```
+
+#### Parameters
+
+```tsx
+interface GetConfigurationsInput {
+  readonly configurationId: string;
+  readonly status?: "ENABLED" | "DISABLED" | "ALL" | "IDLE";
+}
+```
+
+#### Return Value
+
+```tsx
+interface UseConfigurationsReturn {
+  data: Configuration[] | undefined;
+  isLoading: boolean;
+  isError: boolean;
+  error: Error | null;
+  refetch: () => Promise<any>;
+  isFetching: boolean;
+  isSuccess: boolean;
+}
+```
+
+#### Configuration Type
+
+```tsx
+interface Configuration {
+  readonly id: string;
+  readonly connectorId: string;
+  readonly configurationId: string;
+  readonly name: string;
+  readonly flowId: string;
+  readonly description: string;
+  readonly imageUri: string;
+  readonly status: string;
+  readonly actions: readonly ConfigurationAction[];
+  readonly metadata?: unknown;
+}
+
+interface ConfigurationAction {
+  readonly name: string;
+  readonly actionType: ConfigurationActionType;
+  readonly onClick?: () => Promise<void>;
+  readonly form?: ConnectorForm | null;
+  readonly onSubmit?: (formData: unknown) => Promise<void>;
+}
+
+type ConfigurationActionType = ConnectorActionType.ENABLE | ConnectorActionType.DISABLE | ConnectorActionType.DELETE;
+```
+
+### useConfigurationForm
+
+Fetches and manages configuration forms for setting up connectors.
+
+#### Usage
+
+```tsx
+import { useConfigurationForm } from '@fastn-ai/react-core';
+
+function ConfigurationForm({ 
+  configurationId, 
+  connectorId, 
+  configuration 
+}: {
+  configurationId: string;
+  connectorId: string;
+  configuration: Configuration;
+}) {
+  const { 
+    data: form, 
+    isLoading, 
+    error 
+  } = useConfigurationForm({
+    configurationId,
+    connectorId,
+    configuration
+  });
+
+  if (isLoading) return <FormSkeleton />;
+  if (error) return <ErrorMessage error={error} />;
+  if (!form) return <div>No form available</div>;
+
+  return (
+    <ConfigurationFormRenderer 
+      form={form}
+      onSubmit={handleSubmit}
+      onCancel={handleCancel}
+    />
+  );
+}
+```
+
+#### Parameters
+
+```tsx
+interface GetConfigurationFormInput {
+  readonly configurationId: string;
+  readonly connectorId: string;
+  readonly configuration: Configuration;
+}
+```
+
+#### Return Value
+
+```tsx
+interface UseConfigurationFormReturn {
+  data: ConfigurationForm | undefined;
+  isLoading: boolean;
+  isError: boolean;
+  error: Error | null;
+  refetch: () => Promise<any>;
+  isFetching: boolean;
+  isSuccess: boolean;
+}
+```
+
+#### ConfigurationForm Type
+
+```tsx
+interface ConfigurationForm {
+  readonly name: string;
+  readonly description: string;
+  readonly imageUri: string;
+  readonly fields: readonly ConnectorField[];
+  readonly submitButtonLabel?: string;
+  readonly loading?: boolean;
+  readonly error?: string;
+  readonly submitHandler?: (args: { formData: FormData }) => Promise<void>;
+}
+```
+
+### useFieldOptions
+
+Manages async select field options with search, pagination, and caching.
+
+#### Usage
+
+```tsx
+import { useFieldOptions } from '@fastn-ai/react-core';
+
+function AsyncSelectField({ field }: { field: ConnectorField }) {
+  const {
+    options,
+    loading,
+    loadingMore,
+    hasNext,
+    query,
+    refresh,
+    search,
+    loadMore,
+    error
+  } = useFieldOptions(field);
+
+  return (
+    <div>
+      <AsyncSelect
+        options={options}
+        isLoading={loading}
+        onInputChange={search}
+        onMenuScrollToBottom={loadMore}
+        loadMore={loadingMore}
+        hasMore={hasNext}
+        onRefresh={refresh}
+        placeholder={field.placeholder}
+        isClearable
+        isSearchable
+      />
+      {error && <ErrorMessage error={error} />}
+    </div>
+  );
+}
+```
+
+#### Return Value
+
+```tsx
+interface UseFieldOptionsReturn {
+  options: SelectOption[];
+  loading: boolean;
+  loadingMore: boolean;
+  hasNext: boolean;
+  query: string;
+  refresh: () => Promise<void>;
+  search: (query: string) => void;
+  loadMore: () => Promise<void>;
+  totalLoadedOptions: number;
+  error: string | null;
+}
+```
+
+#### SelectOption Type
+
+```tsx
+interface SelectOption {
+  readonly label: string;
+  readonly value: string;
+}
+```
+
+## 🎨 Component Examples
+
+### Connector Card Component
+
+```tsx
+import { useConnectors } from '@fastn-ai/react-core';
+import type { Connector } from '@fastn-ai/react-core';
+
+interface ConnectorCardProps {
+  connector: Connector;
+  onRefresh?: () => void;
+}
+
+function ConnectorCard({ connector, onRefresh }: ConnectorCardProps) {
+  const handleAction = async (action: ConnectorAction) => {
+    try {
+      if (action.onClick) {
+        await action.onClick();
+        onRefresh?.();
+      }
+    } catch (error) {
+      console.error('Action failed:', error);
+    }
+  };
+
+  return (
+    <div className="border rounded-lg p-6 shadow-sm hover:shadow-md transition-shadow">
+      <div className="flex items-center space-x-4">
+        {connector.imageUri && (
+          <img 
+            src={connector.imageUri} 
+            alt={connector.name}
+            className="w-12 h-12 rounded-lg object-cover"
+          />
+        )}
+        <div className="flex-1">
+          <h3 className="text-lg font-semibold text-gray-900">
+            {connector.name}
+          </h3>
+          <p className="text-sm text-gray-600">
+            {connector.description}
+          </p>
+          <span className={`inline-flex px-2 py-1 text-xs font-medium rounded-full ${
+            connector.status === 'ACTIVE' 
+              ? 'bg-green-100 text-green-800' 
+              : 'bg-gray-100 text-gray-800'
+          }`}>
+            {connector.status}
+          </span>
+        </div>
+      </div>
+      
+      <div className="mt-4 flex space-x-2">
+        {connector.actions.map((action, index) => (
+          <button
+            key={index}
+            onClick={() => handleAction(action)}
+            className={`px-4 py-2 text-sm font-medium rounded-md transition-colors ${
+              action.actionType === 'ACTIVATION' || action.actionType === 'ENABLE'
+                ? 'bg-blue-600 text-white hover:bg-blue-700'
+                : action.actionType === 'DEACTIVATION' || action.actionType === 'DISABLE'
+                ? 'bg-red-600 text-white hover:bg-red-700'
+                : 'bg-gray-600 text-white hover:bg-gray-700'
+            }`}
+          >
+            {action.name}
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+### Configuration Card Component
+
+```tsx
+import { useConfigurations } from '@fastn-ai/react-core';
+import type { Configuration } from '@fastn-ai/react-core';
+
+interface ConfigurationCardProps {
+  configuration: Configuration;
+}
+
+function ConfigurationCard({ configuration }: ConfigurationCardProps) {
+  const handleAction = async (action: ConfigurationAction) => {
+    try {
+      if (action.onClick) {
+        await action.onClick();
+      }
+    } catch (error) {
+      console.error('Configuration action failed:', error);
+    }
+  };
+
+  return (
+    <div className="border rounded-lg p-6 shadow-sm">
+      <div className="flex items-center space-x-4">
+        <img 
+          src={configuration.imageUri} 
+          alt={configuration.name}
+          className="w-12 h-12 rounded-lg object-cover"
+        />
+        <div className="flex-1">
+          <h3 className="text-lg font-semibold text-gray-900">
+            {configuration.name}
+          </h3>
+          <p className="text-sm text-gray-600">
+            {configuration.description}
+          </p>
+          <div className="flex items-center space-x-2 mt-2">
+            <span className={`inline-flex px-2 py-1 text-xs font-medium rounded-full ${
+              configuration.status === 'ENABLED' 
+                ? 'bg-green-100 text-green-800' 
+                : configuration.status === 'DISABLED'
+                ? 'bg-red-100 text-red-800'
+                : 'bg-yellow-100 text-yellow-800'
+            }`}>
+              {configuration.status}
+            </span>
+            <span className="text-xs text-gray-500">
+              ID: {configuration.id}
+            </span>
+          </div>
+        </div>
+      </div>
+      
+      <div className="mt-4 flex space-x-2">
+        {configuration.actions.map((action, index) => (
+          <button
+            key={index}
+            onClick={() => handleAction(action)}
+            className={`px-4 py-2 text-sm font-medium rounded-md transition-colors ${
+              action.actionType === 'ENABLE'
+                ? 'bg-green-600 text-white hover:bg-green-700'
+                : action.actionType === 'DISABLE'
+                ? 'bg-yellow-600 text-white hover:bg-yellow-700'
+                : action.actionType === 'DELETE'
+                ? 'bg-red-600 text-white hover:bg-red-700'
+                : 'bg-gray-600 text-white hover:bg-gray-700'
+            }`}
+          >
+            {action.name}
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+### Configuration Form Renderer
+
+```tsx
+import { useConfigurationForm, useFieldOptions } from '@fastn-ai/react-core';
+import type { ConfigurationForm, ConnectorField } from '@fastn-ai/react-core';
+
+interface ConfigurationFormRendererProps {
+  form: ConfigurationForm;
+  onSubmit: (formData: Record<string, any>) => Promise<void>;
+  onCancel: () => void;
+}
+
+function ConfigurationFormRenderer({ 
+  form, 
+  onSubmit, 
+  onCancel 
+}: ConfigurationFormRendererProps) {
+  const [formData, setFormData] = useState<Record<string, any>>({});
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setIsSubmitting(true);
+    
+    try {
+      await onSubmit(formData);
+    } catch (error) {
+      console.error('Form submission failed:', error);
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
+  const renderField = (field: ConnectorField) => {
+    switch (field.type) {
+      case 'text':
+      case 'email':
+      case 'password':
+        return (
+          <input
+            type={field.type}
+            name={field.key}
+            placeholder={field.placeholder}
+            required={field.required}
+            disabled={field.disabled}
+            value={formData[field.key] || ''}
+            onChange={(e) => setFormData(prev => ({
+              ...prev,
+              [field.key]: e.target.value
+            }))}
+            className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+          />
+        );
+        
+      case 'select':
+        return <AsyncSelectField field={field} />;
+        
+      case 'multi-select':
+        return <AsyncMultiSelectField field={field} />;
+        
+      case 'number':
+        return (
+          <input
+            type="number"
+            name={field.key}
+            placeholder={field.placeholder}
+            required={field.required}
+            disabled={field.disabled}
+            value={formData[field.key] || ''}
+            onChange={(e) => setFormData(prev => ({
+              ...prev,
+              [field.key]: e.target.value
+            }))}
+            className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+          />
+        );
+        
+      case 'checkbox':
+        return (
+          <input
+            type="checkbox"
+            name={field.key}
+            required={field.required}
+            disabled={field.disabled}
+            checked={formData[field.key] || false}
+            onChange={(e) => setFormData(prev => ({
+              ...prev,
+              [field.key]: e.target.checked
+            }))}
+            className="w-4 h-4 text-blue-600 border-gray-300 rounded focus:ring-blue-500"
+          />
+        );
+        
+      default:
+        return (
+          <input
+            type="text"
+            name={field.key}
+            placeholder={field.placeholder}
+            required={field.required}
+            disabled={field.disabled}
+            value={formData[field.key] || ''}
+            onChange={(e) => setFormData(prev => ({
+              ...prev,
+              [field.key]: e.target.value
+            }))}
+            className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+          />
+        );
+    }
+  };
+
+  return (
+    <div className="max-w-2xl mx-auto p-6 bg-white rounded-lg shadow-lg">
+      <div className="mb-6">
+        <h2 className="text-2xl font-bold text-gray-900">{form.name}</h2>
+        <p className="text-gray-600 mt-2">{form.description}</p>
+      </div>
+      
+      <form onSubmit={handleSubmit} className="space-y-6">
+        {form.fields.map((field) => (
+          <div key={field.key} className="space-y-2">
+            <label className="block text-sm font-medium text-gray-700">
+              {field.label}
+              {field.required && <span className="text-red-500 ml-1">*</span>}
+            </label>
+            {renderField(field)}
+            {field.description && (
+              <p className="text-sm text-gray-500">{field.description}</p>
+            )}
+          </div>
+        ))}
+        
+        <div className="flex space-x-4 pt-6">
+          <button
+            type="submit"
+            disabled={isSubmitting}
+            className="flex-1 bg-blue-600 text-white py-2 px-4 rounded-md hover:bg-blue-700 disabled:opacity-50 disabled:cursor-not-allowed"
+          >
+            {isSubmitting ? 'Saving...' : (form.submitButtonLabel || 'Save Configuration')}
+          </button>
+          <button
+            type="button"
+            onClick={onCancel}
+            className="flex-1 bg-gray-300 text-gray-700 py-2 px-4 rounded-md hover:bg-gray-400"
+          >
+            Cancel
+          </button>
+        </div>
+      </form>
+    </div>
+  );
+}
+```
+
+### Async Select Field Component
+
+```tsx
+import { useFieldOptions } from '@fastn-ai/react-core';
+import type { ConnectorField, SelectOption } from '@fastn-ai/react-core';
+
+interface AsyncSelectFieldProps {
+  field: ConnectorField;
+  value?: SelectOption | null;
+  onChange?: (option: SelectOption | null) => void;
+}
+
+function AsyncSelectField({ field, value, onChange }: AsyncSelectFieldProps) {
+  const {
+    options,
+    loading,
+    loadingMore,
+    hasNext,
+    query,
+    refresh,
+    search,
+    loadMore,
+    error
+  } = useFieldOptions(field);
+
+  const handleInputChange = (inputValue: string) => {
+    search(inputValue);
+  };
+
+  const handleMenuScrollToBottom = () => {
+    if (hasNext && !loadingMore) {
+      loadMore();
+    }
+  };
+
+  return (
+    <div className="relative">
+      <select
+        value={value?.value || ''}
+        onChange={(e) => {
+          const option = options.find(opt => opt.value === e.target.value);
+          onChange?.(option || null);
+        }}
+        disabled={loading}
+        className="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500"
+      >
+        <option value="">{field.placeholder || 'Select an option...'}</option>
+        {options.map((option) => (
+          <option key={option.value} value={option.value}>
+            {option.label}
+          </option>
+        ))}
+      </select>
+      
+      {loading && (
+        <div className="absolute right-3 top-1/2 transform -translate-y-1/2">
+          <div className="animate-spin rounded-full h-4 w-4 border-b-2 border-blue-600"></div>
+        </div>
+      )}
+      
+      {hasNext && (
+        <button
+          type="button"
+          onClick={loadMore}
+          disabled={loadingMore}
+          className="mt-2 text-sm text-blue-600 hover:text-blue-800 disabled:opacity-50"
+        >
+          {loadingMore ? 'Loading more...' : 'Load more options'}
+        </button>
+      )}
+      
+      {error && (
+        <p className="mt-1 text-sm text-red-600">{error}</p>
+      )}
+    </div>
+  );
+}
+```
+
+## 🔧 Advanced Usage
+
+### Custom Error Handling
+
+```tsx
+import { useConnectors } from '@fastn-ai/react-core';
+
+function ConnectorsWithErrorHandling() {
+  const { data: connectors, isLoading, error, refetch } = useConnectors();
+
+  if (error) {
+    return (
+      <div className="bg-red-50 border border-red-200 rounded-md p-4">
+        <div className="flex">
+          <div className="flex-shrink-0">
+            <svg className="h-5 w-5 text-red-400" viewBox="0 0 20 20" fill="currentColor">
+              <path fillRule="evenodd" d="M10 18a8 8 0 100-16 8 8 0 000 16zM8.707 7.293a1 1 0 00-1.414 1.414L8.586 10l-1.293 1.293a1 1 0 101.414 1.414L10 11.414l1.293 1.293a1 1 0 001.414-1.414L11.414 10l1.293-1.293a1 1 0 00-1.414-1.414L10 8.586 8.707 7.293z" clipRule="evenodd" />
+            </svg>
+          </div>
+          <div className="ml-3">
+            <h3 className="text-sm font-medium text-red-800">
+              Failed to load connectors
+            </h3>
+            <div className="mt-2 text-sm text-red-700">
+              <p>{error.message}</p>
+            </div>
+            <div className="mt-4">
+              <button
+                onClick={() => refetch()}
+                className="bg-red-100 text-red-800 px-3 py-2 rounded-md text-sm font-medium hover:bg-red-200"
+              >
+                Try again
+              </button>
+            </div>
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  // ... rest of component
+}
+```
+
+### Optimistic Updates
+
+```tsx
+import { useConnectors } from '@fastn-ai/react-core';
+import { useQueryClient } from '@tanstack/react-query';
+
+function ConnectorWithOptimisticUpdate({ connector }: { connector: Connector }) {
+  const queryClient = useQueryClient();
+
+  const handleAction = async (action: ConnectorAction) => {
+    if (!action.onClick) return;
+
+    // Optimistically update the UI
+    queryClient.setQueryData(['connectors'], (oldData: Connector[] | undefined) => {
+      if (!oldData) return oldData;
+      
+      return oldData.map(conn => {
+        if (conn.id === connector.id) {
+          return {
+            ...conn,
+            status: action.actionType === 'ACTIVATION' ? 'ACTIVE' : 'INACTIVE'
+          };
+        }
+        return conn;
+      });
+    });
+
+    try {
+      await action.onClick();
+      // Refetch to ensure data consistency
+      queryClient.invalidateQueries(['connectors']);
+    } catch (error) {
+      // Revert optimistic update on error
+      queryClient.invalidateQueries(['connectors']);
+      console.error('Action failed:', error);
+    }
+  };
+
+  // ... rest of component
+}
+```
+
+### Custom Styling with CSS-in-JS
+
+```tsx
+import { useConnectors } from '@fastn-ai/react-core';
+import styled from 'styled-components';
+
+const ConnectorGrid = styled.div`
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
+  gap: 1.5rem;
+  padding: 1rem;
+`;
+
+const ConnectorCard = styled.div`
+  background: white;
+  border: 1px solid #e5e7eb;
+  border-radius: 0.5rem;
+  padding: 1.5rem;
+  transition: all 0.2s ease;
+  
+  &:hover {
+    box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
+    transform: translateY(-2px);
+  }
+`;
+
+const ActionButton = styled.button<{ variant: 'primary' | 'secondary' | 'danger' }>`
+  padding: 0.5rem 1rem;
+  border-radius: 0.375rem;
+  font-weight: 500;
+  transition: all 0.2s ease;
+  
+  ${({ variant }) => {
+    switch (variant) {
+      case 'primary':
+        return `
+          background: #3b82f6;
+          color: white;
+          &:hover { background: #2563eb; }
+        `;
+      case 'secondary':
+        return `
+          background: #6b7280;
+          color: white;
+          &:hover { background: #4b5563; }
+        `;
+      case 'danger':
+        return `
+          background: #dc2626;
+          color: white;
+          &:hover { background: #b91c1c; }
+        `;
+    }
+  }}
+`;
+
+function StyledConnectorsList() {
+  const { data: connectors, isLoading, error } = useConnectors();
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <ConnectorGrid>
+      {connectors?.map(connector => (
+        <ConnectorCard key={connector.id}>
+          <h3>{connector.name}</h3>
+          <p>{connector.description}</p>
+          <div>
+            {connector.actions.map((action, index) => (
+              <ActionButton
+                key={index}
+                variant={
+                  action.actionType === 'ACTIVATION' ? 'primary' :
+                  action.actionType === 'DEACTIVATION' ? 'danger' : 'secondary'
+                }
+                onClick={() => action.onClick?.()}
+              >
+                {action.name}
+              </ActionButton>
+            ))}
+          </div>
+        </ConnectorCard>
+      ))}
+    </ConnectorGrid>
+  );
+}
+```
+
+## 🎯 Best Practices
+
+### 1. Error Boundaries
+
+Wrap your Fastn components with error boundaries to handle unexpected errors gracefully:
+
+```tsx
+import { ErrorBoundary } from 'react-error-boundary';
+
+function ErrorFallback({ error, resetErrorBoundary }: { error: Error; resetErrorBoundary: () => void }) {
+  return (
+    <div className="text-center p-6">
+      <h2 className="text-lg font-semibold text-gray-900">Something went wrong</h2>
+      <p className="text-gray-600 mt-2">{error.message}</p>
+      <button
+        onClick={resetErrorBoundary}
+        className="mt-4 bg-blue-600 text-white px-4 py-2 rounded-md hover:bg-blue-700"
+      >
+        Try again
+      </button>
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <FastnProvider config={config}>
+      <ErrorBoundary FallbackComponent={ErrorFallback}>
+        <YourApp />
+      </ErrorBoundary>
+    </FastnProvider>
+  );
+}
+```
+
+### 2. Loading States
+
+Always provide meaningful loading states for better user experience:
+
+```tsx
+function LoadingSkeleton() {
+  return (
+    <div className="animate-pulse">
+      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
+        {[...Array(6)].map((_, i) => (
+          <div key={i} className="border rounded-lg p-6">
+            <div className="flex items-center space-x-4">
+              <div className="w-12 h-12 bg-gray-200 rounded-lg"></div>
+              <div className="flex-1">
+                <div className="h-4 bg-gray-200 rounded w-3/4 mb-2"></div>
+                <div className="h-3 bg-gray-200 rounded w-1/2"></div>
+              </div>
+            </div>
+            <div className="mt-4 flex space-x-2">
+              <div className="h-8 bg-gray-200 rounded w-20"></div>
+              <div className="h-8 bg-gray-200 rounded w-20"></div>
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+### 3. Type Safety
+
+Always use TypeScript interfaces for better type safety:
+
+```tsx
+import type { 
+  Connector, 
+  Configuration, 
+  ConfigurationForm,
+  ConnectorField 
+} from '@fastn-ai/react-core';
+
+interface ConnectorCardProps {
+  connector: Connector;
+  onAction?: (action: ConnectorAction) => Promise<void>;
+  className?: string;
+}
+
+interface ConfigurationFormProps {
+  form: ConfigurationForm;
+  onSubmit: (data: Record<string, any>) => Promise<void>;
+  onCancel: () => void;
+  loading?: boolean;
+}
+```
+
+### 4. Performance Optimization
+
+Use React.memo and useMemo for expensive operations:
+
+```tsx
+import { memo, useMemo } from 'react';
+
+const ConnectorCard = memo(({ connector, onAction }: ConnectorCardProps) => {
+  const statusColor = useMemo(() => {
+    return connector.status === 'ACTIVE' ? 'green' : 'gray';
+  }, [connector.status]);
+
+  const actionButtons = useMemo(() => {
+    return connector.actions.map((action, index) => (
+      <button
+        key={index}
+        onClick={() => onAction?.(action)}
+        className={`px-4 py-2 rounded-md ${
+          action.actionType === 'ACTIVATION' 
+            ? 'bg-blue-600 text-white' 
+            : 'bg-gray-600 text-white'
+        }`}
+      >
+        {action.name}
+      </button>
+    ));
+  }, [connector.actions, onAction]);
+
+  return (
+    <div className="border rounded-lg p-6">
+      <h3>{connector.name}</h3>
+      <p>{connector.description}</p>
+      <div className="flex space-x-2 mt-4">
+        {actionButtons}
+      </div>
+    </div>
+  );
+});
+
+ConnectorCard.displayName = 'ConnectorCard';
+```
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+#### 1. Provider Not Found Error
+
+**Error**: `Initialize Fastn with FastnProvider first`
+
+**Solution**: Make sure your component is wrapped with `FastnProvider`:
+
+```tsx
+// ❌ Wrong - Component outside provider
+function MyComponent() {
+  const { data } = useConnectors(); // This will throw an error
+  return <div>...</div>;
+}
+
+// ✅ Correct - Component inside provider
+function App() {
+  return (
+    <FastnProvider config={config}>
+      <MyComponent />
+    </FastnProvider>
+  );
+}
+```
+
+#### 2. Authentication Errors
+
+**Error**: `401 Unauthorized` or `403 Forbidden`
+
+**Solution**: Check your configuration:
+
+```tsx
+const config = {
+  authToken: 'your-valid-auth-token', // Make sure this is valid
+  tenantId: 'your-tenant-id',
+  spaceId: 'your-space-id',
+  // ... other config
+};
+```
+
+#### 3. Network Errors
+
+**Error**: `Network Error` or `Failed to fetch`
+
+**Solution**: Check your base URL and network connectivity:
+
+```tsx
+const config = {
+  baseUrl: 'https://api.fastn.ai', // Make sure this is correct
+  // ... other config
+};
+```
+
+#### 4. TypeScript Errors
+
+**Error**: Type mismatches or missing types
+
+**Solution**: Import types explicitly:
+
+```tsx
+import type { 
+  Connector, 
+  Configuration, 
+  ConnectorAction,
+  ConfigurationAction 
+} from '@fastn-ai/react-core';
+```
+
+### Debug Mode
+
+Enable debug logging to troubleshoot issues:
+
+```tsx
+// Add this to your app to see detailed logs
+if (process.env.NODE_ENV === 'development') {
+  console.log('Fastn Config:', config);
+}
+```
+
+## 📚 Additional Resources
+
+- [Fastn AI Documentation](https://docs.fastn.ai)
+- [React Query Documentation](https://tanstack.com/query/latest)
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🆘 Support
+
+If you need help or have questions:
+
+- 📧 Email: [support@fastn.ai](mailto:support@fastn.ai)
+- 📖 Documentation: [docs.fastn.ai](https://docs.fastn.ai)
+- 🐛 Issues: [GitHub Issues](https://github.com/fastn-ai/react-core/issues)
+
+---
+
+Made with ❤️ by the Fastn team -->
+
+
+# @fastn-ai/react-core
+
+A React library for integrating Fastn AI connectors into your application. This package provides hooks and types to manage connectors, configurations, and dynamic configuration forms, allowing you to build your own UI on top of Fastn's data and logic.
+
+## Features
+
+- Manage and list connectors
+- Handle connector configurations
+- Render and submit dynamic configuration forms
+- Powered by React Query (supports custom or existing clients)
+
+## Installation
+
+```bash
+npm install @fastn-ai/react-core
+```
+
+### Peer Dependencies
+
+You need React 18+ and React Query. Install if not already present:
+
+```bash
+npm install react react-dom @tanstack/react-query
+```
+
+## Initialization
+
+### 1. Basic Setup
+
+Wrap your app with `FastnProvider` and provide your configuration. This will create its own React Query client by default.
+
+```tsx
+import { FastnProvider } from "@fastn-ai/react-core";
+
+const fastnConfig = {
+  environment: "LIVE", // or 'DRAFT' or custom string
+  authToken: "your-auth-token",
+  tenantId: "your-tenant-id",
+  spaceId: "your-space-id",
+};
+
+function App() {
+  return (
+    <FastnProvider config={fastnConfig}>
+      {/* Your app components here */}
+    </FastnProvider>
+  );
+}
+```
+
+### 2. Using an Existing React Query Client
+
+If your app already uses React Query, you can pass your own client:
+
+```tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { FastnProvider } from "@fastn-ai/react-core";
+
+const queryClient = new QueryClient();
+const fastnConfig = { /* ... */ };
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <FastnProvider config={fastnConfig}>
+        {/* Your app components here */}
+      </FastnProvider>
+    </QueryClientProvider>
+  );
+}
+```
+
+## Usage
+
+### 1. Fetching Connectors
+
+Use the `useConnectors` hook to get the list of available connectors. You can render them however you like.
+
+```tsx
+import { useConnectors } from "@fastn-ai/react-core";
+
+function ConnectorsList() {
+  const { data: connectors, isLoading, error } = useConnectors();
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <ul>
+      {connectors?.map((connector) => (
+        <li key={connector.id}>{connector.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+#### Types
+
+```ts
+interface Connector {
+  id: string;
+  name: string;
+  description: string;
+  imageUri?: string;
+  status: ConnectorStatus;
+  actions: ConnectorAction[];
+}
+
+enum ConnectorStatus {
+  ACTIVE = "ACTIVE",
+  INACTIVE = "INACTIVE",
+  ALL = "ALL",
+}
+
+interface ConnectorAction {
+  name: string;
+  actionType: ConnectorActionType | string;
+  form?: ConnectorForm | null;
+  onClick?: (data?: unknown) => Promise<ConnectorActionResult>;
+  onSubmit?: (formData: Record<string, unknown>) => Promise<ConnectorActionResult>;
+}
+
+interface ConnectorActionResult {
+  data: unknown;
+  status: "SUCCESS" | "ERROR" | "CANCELLED;
+}
+
+enum ConnectorActionType {
+  ACTIVATION = "ACTIVATION",
+  DEACTIVATION = "DEACTIVATION",
+  NONE = "NONE",
+}
+```
+
+### 2. Fetching Configurations
+
+Use the `useConfigurations` hook to get connector configurations for a given configuration ID.
+
+```tsx
+import { useConfigurations } from "@fastn-ai/react-core";
+
+function ConfigurationsList({ configurationId }: { configurationId: string }) {
+  const { data: configurations, isLoading, error } = useConfigurations({
+    configurationId,
+    status: "ALL", // 'ENABLED' | 'DISABLED' | 'ALL'
+  });
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <ul>
+      {configurations?.map((config) => (
+        <li key={config.id}>{config.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+#### Types
+
+```ts
+interface Configuration {
+  id: string;
+  connectorId: string;
+  configurationId: string;
+  name: string;
+  flowId: string;
+  description: string;
+  imageUri: string;
+  status: string;
+  actions: ConfigurationAction[];
+  metadata?: unknown;
+}
+
+interface ConfigurationAction {
+  name: string;
+  actionType: ConfigurationActionType;
+  onClick?: () => Promise<ConnectorActionResult>;
+  form?: ConnectorForm | null;
+  onSubmit?: (formData: unknown) => Promise<ConnectorActionResult>;
+}
+
+type ConfigurationActionType =
+  | ConnectorActionType.ENABLE
+  | ConnectorActionType.DISABLE
+  | ConnectorActionType.DELETE;
+```
+
+### 3. Dynamic Configuration Forms
+
+Use the `useConfigurationForm` hook to fetch a configuration form for a connector or configuration. You can render the form fields as you wish.
+
+```tsx
+import { useConfigurationForm } from "@fastn-ai/react-core";
+
+function ConfigurationForm({ configurationId }: { configurationId: string }) {
+  const { data: configurationForm, isLoading, error } = useConfigurationForm({ configurationId });
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <form onSubmit={/* your submit handler */}>
+      {configurationForm.fields.map((field) => (
+        // Render your input based on field.type and field.options
+        <div key={field.name}>{field.label}</div>
+      ))}
+      <button type="submit">Submit</button>
+    </form>
+  );
+}
+```
+
+#### Types
+
+```ts
+interface ConfigurationForm {
+  name: string;
+  description: string;
+  imageUri: string;
+  fields: ConnectorField[];
+  submitHandler: (formData: unknown) => Promise<void>;
+}
+
+interface ConnectorField {
+  name: string;
+  label: string;
+  type: string; // e.g. 'text', 'select', etc.
+  required?: boolean;
+  options?: Array<{ label: string; value: string }>;
+  // ...other field properties
+}
+```
+
+### 4. Select Fields and Google Drive File Picker (Advanced Field Handling)
+
+Handling dynamic select fields and Google Drive file pickers is the most advanced part of integrating Fastn AI connectors. This section provides a comprehensive guide to implementing these fields in your own UI.
+
+#### Select Fields (Single & Multi-Select)
+
+For fields of type `select` or `multi-select`, use the `useFieldOptions` hook to fetch options, handle search, pagination, and errors. This hook abstracts away the complexity of loading options from remote sources, searching, and paginating.
+
+**Example: Generic SelectField Component**
+
+```tsx
+import { useFieldOptions } from "@fastn-ai/react-core";
+
+function SelectField({ field, value, onChange, isMulti = false }) {
+  // useFieldOptions provides all logic for options, loading, errors, search, pagination, etc.
+  const {
+    options,
+    loading,
+    loadingMore,
+    hasNext,
+    loadMore,
+    error,
+    search,
+    refresh,
+    totalLoadedOptions,
+  } = useFieldOptions(field);
+
+  // Handle search input
+  function handleInputChange(e) {
+    search(e.target.value);
+  }
+
+  // Handle loading more options (pagination)
+  function handleLoadMore() {
+    if (hasNext && !loadingMore) loadMore();
+  }
+
+  // Handle refresh on error
+  function handleRefresh() {
+    refresh();
+  }
+
+  return (
+    <div>
+      <label>{field.label}{field.required && ' *'}</label>
+      {error && (
+        <div>
+          <span style={{ color: 'red' }}>Error loading options</span>
+          <button type="button" onClick={handleRefresh}>Retry</button>
+        </div>
+      )}
+      <input
+        type="text"
+        placeholder={field.placeholder || `Search ${field.label}`}
+        onChange={handleInputChange}
+        disabled={loading}
+      />
+      <select
+        multiple={isMulti}
+        value={value}
+        onChange={e => {
+          if (isMulti) {
+            const selected = Array.from(e.target.selectedOptions, o => o.value);
+            onChange(selected);
+          } else {
+            onChange(e.target.value);
+          }
+        }}
+        disabled={loading}
+      >
+        {options.map(opt => (
+          <option key={opt.value} value={opt.value}>{opt.label}</option>
+        ))}
+      </select>
+      {loading && <div>Loading options...</div>}
+      {hasNext && !loadingMore && (
+        <button type="button" onClick={handleLoadMore}>Load More</button>
+      )}
+      {loadingMore && <div>Loading more...</div>}
+      <div>Loaded {totalLoadedOptions} options{hasNext ? '' : ' (all loaded)'}</div>
+      {field.description && <div style={{ fontSize: 'smaller', color: '#666' }}>{field.description}</div>}
+    </div>
+  );
+}
+```
+
+**Key Points:**
+- `useFieldOptions(field)` returns all logic for options, loading, errors, search, pagination, and refresh.
+- Use `search` for filtering options, `loadMore` for pagination, and `refresh` to retry on error.
+- The component above is generic and can be styled or replaced with any UI library (e.g., react-select).
+
+**useFieldOptions Return Type:**
+```ts
+interface UseFieldOptionsReturn {
+  options: Array<{ label: string; value: string }>;
+  loading: boolean;
+  loadingMore: boolean;
+  hasNext: boolean;
+  loadMore: () => Promise<void>;
+  error: string | null;
+  search: (query: string) => void;
+  refresh: () => void;
+  totalLoadedOptions: number;
+}
+```
+
+#### Google Drive File Picker Field
+
+For fields that require Google Drive file selection, the field type will be something like `select_with_google_files_picker` or similar. These fields provide an `optionsSource` with a method to open the Google Files Picker dialog.
+
+**Example: GoogleFilesPickerField Component**
+
+```tsx
+function GoogleFilesPickerField({ field, value, onChange, isMulti = false }) {
+  // This field may also use useFieldOptions for listing previously picked files
+  const { options, loading, error, refresh } = useFieldOptions(field);
+
+  // Handler to open Google Drive picker
+  async function handlePickFiles() {
+    if (field.optionsSource?.openGoogleFilesPicker) {
+      await field.optionsSource.openGoogleFilesPicker({
+        onComplete: async (files) => {
+          // files is an array of selected file objects
+          if (isMulti) {
+            onChange(files);
+          } else {
+            onChange(files[0]);
+          }
+        },
+        onError: async (pickerError) => {
+          // Handle picker error (optional)
+          alert('Google Files Picker error: ' + pickerError);
+        },
+      });
+    }
+  }
+
+  return (
+    <div>
+      <label>{field.label}{field.required && ' *'}</label>
+      {error && (
+        <div>
+          <span style={{ color: 'red' }}>Error loading files</span>
+          <button type="button" onClick={refresh}>Retry</button>
+        </div>
+      )}
+      <button type="button" onClick={handlePickFiles} disabled={loading}>
+        Pick from Google Drive
+      </button>
+      {value && (
+        <div>
+          <strong>Selected file{isMulti ? 's' : ''}:</strong>
+          <ul>
+            {(isMulti ? value : [value]).map((file, idx) => (
+              <li key={file.id || idx}>{file.name || file.id}</li>
+            ))}
+          </ul>
+        </div>
+      )}
+      {field.description && <div style={{ fontSize: 'smaller', color: '#666' }}>{field.description}</div>}
+    </div>
+  );
+}
+```
+
+**Key Points:**
+- The `openGoogleFilesPicker` method is provided on the field's `optionsSource` property.
+- The `onComplete` callback receives the selected files (array of file objects).
+- You can display the selected files as you wish.
+- This field can be used in both single and multi-select modes.
+
+**GoogleFilesPicker Return Type:**
+```ts
+interface UseGoogleFilesPickerReturn {
+  options: Array<{ label: string; value: string }>;
+  loading: boolean;
+  loadingMore: boolean;
+  hasNext: boolean;
+  query: string;
+  refresh: () => Promise<void>;
+  search: (query: string) => void;
+  loadMore: () => Promise<void>;
+  totalLoadedOptions: number;
+  error: string | null;
+}
+```
+
+**Integrating with Forms**
+- For both SelectField and GoogleFilesPickerField, you can use them as controlled components in your form library (Formik, React Hook Form, etc.).
+- The value and onChange props should be managed by your form state.
+- You can combine these fields with other input types to build a complete dynamic configuration form.
+
+---
+
+## Error Handling & Troubleshooting
+
+- **Provider Not Found**: Ensure your components are wrapped in `FastnProvider`.
+- **Authentication Errors**: Check your `authToken`, `tenantId`, and `spaceId`.
+- **Network Errors**: Verify your network and API base URL.
+- **TypeScript Errors**: Import types from the package as needed.
+
+## TypeScript Support
+
+All hooks and data structures are fully typed. You can import types directly:
+
+```ts
+import type { Connector, Configuration, ConnectorAction, ConfigurationAction } from '@fastn-ai/react-core';
+```
+
+## License
+
+MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Support
+
+- Email: support@fastn.ai
+- Documentation: https://docs.fastn.ai
+- Issues: https://github.com/fastn-ai/react-core/issues
+
+---
+
+This package provides the data and logic for Fastn AI connectors. You are free to build your own UI and integrate these hooks and types as needed for your application.