@dev-fastn-ai/react-core 1.0.20 → 2.0.1

package/README.md

@@ -1,75 +1,141 @@
-# @fastn-ai/react-core
+# [Fastn.ai](http://fastn.ai/) React Core Documentation
 
-A React library for integrating Fastn AI connectors into your application. This package provides robust hooks to manage connectors, configurations, and dynamic configuration forms, empowering you to build custom UIs on top of Fastn's data and logic.
+A React library for integrating **Fastn AI connectors** into your application. It provides powerful hooks to manage:
 
----
-
-## Features
+- Connector listing, activation, and deactivation
+- Configuration form rendering and submission
+- Seamless integration with React Query for state management
 
-- List and manage connectors
-- Handle connector configurations
-- Render and submit dynamic configuration forms
-- Powered by React Query (supports custom or existing clients)
+This enables you to **build fully custom UIs** on top of Fastn's powerful data and logic engine.
 
 ---
 
-## Installation
+## 📦 Installation
+
+Install the core library:
 
 ```bash
-npm install @fastn-ai/react-core
+npm install @dev-fastn-ai/react-core
 ```
 
-### Peer Dependencies
-
-Ensure you have React 18+ and React Query installed:
+Also, make sure you install the required **peer dependencies**:
 
 ```bash
 npm install react react-dom @tanstack/react-query
 ```
 
+> ✅ Requires React 18+
+
 ---
 
-## Getting Started
+## 🏗️ Fastn Architecture Concepts
+
+Before diving into the code, let's understand the key Fastn concepts and terminology:
+
+### **Space (Workspace)**
+
+A **Space** (also called Workspace) is the top-level container in Fastn that groups all your connectors, configurations, and data flows. Think of it as your project or organization's workspace where all integrations live.
+
+### **Tenant**
+
+A **Tenant** represents a user, team, or organization within your application. Each tenant has isolated data and configurations. For example:
+
+- A single user account
+- A team within your app
+- An organization or company
+- A client's workspace
+
+### **Connector**
+
+A **Connector** represents an integration with an external service (like Slack, Google Drive, etc.). Connectors define what external services your app can connect to.
+
+### **Configuration**
+
+A **Configuration** is a specific instance of a connector with saved settings and authentication. For example:
+
+- A Slack workspace connection with specific channels selected
+- A Google Drive connection with specific folders configured
+- A database connection with connection parameters
 
-### 1. Basic Setup
+### **Configuration ID**
 
-Wrap your app with `FastnProvider` and provide your configuration. By default, this creates its own React Query client.
+A **Configuration ID** is a unique identifier that represents a specific configuration instance. This ID is used to:
+
+- Load existing configurations
+- Update configuration settings
+- Manage the lifecycle of a specific integration
+
+---
+
+## ⚙️ Features
+
+- **Connector Management**: List, activate, and deactivate connectors
+- **Tenant Isolation**: Each tenant has its own isolated connector state and configurations
+- **Configuration Persistence**: Save and retrieve configurations using unique `configurationId`s
+- **Dynamic Forms**: Render configuration forms using Fastn's form schema
+- **React Query Integration**: Built-in support for efficient caching and request handling
+- **Authentication Flow**: Handle OAuth and custom authentication flows seamlessly
+
+---
+
+## 🚀 Getting Started
+
+### 1. **Wrap Your App with `FastnProvider`**
+
+This sets up Fastn in your app and gives you access to its hooks and logic.
 
 ```tsx
-import { FastnProvider } from "@fastn-ai/react-core";
+import { FastnProvider } from "@dev-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",
+  environment: "LIVE", // "LIVE", "DRAFT", or a custom environment string for widgets
+  authToken: "your-auth-token", // Your app's access token, authenticated through Fastn Custom Auth
+  tenantId: "your-tenant-id", // A unique ID representing the user, team, or organization
+  spaceId: "your-space-id", // Fastn Space ID (also called Workspace ID) - groups all connectors and configurations
 };
 
 function App() {
   return (
     <FastnProvider config={fastnConfig}>
-      {/* Your app components here */}
+      {/* Your app components */}
     </FastnProvider>
   );
 }
 ```
 
-### 2. Using an Existing React Query Client
+### 🔍 Configuration Field Reference
+
+| Field         | Description                                                                                                                  |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `environment` | The widget environment: use `"LIVE"` for production, `"DRAFT"` for preview/testing, or any custom string configured in Fastn |
+| `authToken`   | The token from your authentication flow. Fastn uses this to authenticate the user via the **fastnCustomAuth** flow           |
+| `tenantId`    | A unique identifier for the current user or organization. This helps Fastn isolate data per tenant                           |
+| `spaceId`     | The Fastn **Space ID**, also called the Workspace ID. It groups all connectors, configurations, and flows                    |
+
+---
+
+### 2. **Use an Existing React Query Client (Optional)**
 
 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";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { FastnProvider } from "@dev-fastn-ai/react-core";
 
 const queryClient = new QueryClient();
-const fastnConfig = { /* ... */ };
+
+const fastnConfig = {
+  environment: "LIVE",
+  authToken: "your-auth-token",
+  tenantId: "your-tenant-id",
+  spaceId: "your-space-id",
+};
 
 function App() {
   return (
     <QueryClientProvider client={queryClient}>
       <FastnProvider config={fastnConfig}>
-        {/* Your app components here */}
+        {/* Your app components */}
       </FastnProvider>
     </QueryClientProvider>
   );
@@ -78,34 +144,11 @@ function App() {
 
 ---
 
-## Usage
+## 🧩 Core Hooks & Types
 
-### 1. Fetching Connectors
-
-Use the `useConnectors` hook to retrieve the list of available connectors.
+### **Connector Types**
 
 ```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;
@@ -124,13 +167,10 @@ enum ConnectorStatus {
 interface ConnectorAction {
   name: string;
   actionType: ConnectorActionType | string;
-  form?: ConnectorForm | null;
-  onClick?: (data?: unknown) => Promise<ConnectorActionResult>;
-  onSubmit?: (formData: Record<string, unknown>) => Promise<ConnectorActionResult>;
+  onClick?: () => Promise<ConnectorActionResult>;
 }
 
 interface ConnectorActionResult {
-  data: unknown;
   status: "SUCCESS" | "ERROR" | "CANCELLED";
 }
 
@@ -141,123 +181,439 @@ enum ConnectorActionType {
 }
 ```
 
+### **Configuration Types**
+
+```tsx
+interface Configuration {
+  id: string;
+  connectorId: string;
+  name: string;
+  description: string;
+  imageUri?: string;
+  status: ConfigurationStatus;
+  actions: ConfigurationAction[];
+}
+
+enum ConfigurationStatus {
+  ENABLED = "ENABLED",
+  DISABLED = "DISABLED",
+  PENDING = "PENDING",
+}
+
+interface ConfigurationAction {
+  name: string;
+  actionType: ConfigurationActionType | string;
+  onClick?: () => Promise<ConfigurationActionResult>;
+}
+
+interface ConfigurationActionResult {
+  status: "SUCCESS" | "ERROR" | "CANCELLED";
+}
+
+enum ConfigurationActionType {
+  ENABLE = "ENABLE",
+  DISABLE = "DISABLE",
+  DELETE = "DELETE",
+  UPDATE = "UPDATE",
+}
+```
+
+### **Configuration Form Types**
+
+```tsx
+interface ConfigurationForm {
+  name: string;
+  description: string;
+  imageUri: string;
+  fields: ConnectorField[];
+  submitHandler: (formData: FormData) => Promise<void>;
+}
+
+type FormData =
+  | Record<
+      string,
+      Record<string, Primitive> | Record<string, Primitive>[] | undefined | null
+    >
+  | Record<
+      string,
+      Record<string, Primitive> | Record<string, Primitive>[] | undefined | null
+    >[]
+  | undefined
+  | null;
+
+interface ConnectorField {
+  readonly name: string;
+  readonly key: string;
+  readonly label: string;
+  readonly type: ConnectorFieldType | string;
+  readonly required: boolean;
+  readonly placeholder: string;
+  readonly description: string;
+  readonly hidden?: boolean;
+  readonly disabled?: boolean;
+  readonly initialValue?:
+    | Record<string, Primitive>
+    | Record<string, Primitive>[]
+    | Primitive
+    | Primitive[];
+  readonly optionsSource?: SelectOptionSource;
+}
+```
+
 ---
 
-### 2. Fetching Configurations
+## 🔄 Complete Integration Workflows
+
+### **Workflow 1: Setting Up Your First Slack Integration**
 
-Use the `useConfigurations` hook to get connector configurations for a given configuration ID.
+Let's walk through a complete example of setting up a Slack integration from scratch.
+
+#### Step 1: List Available Connectors
+
+First, show users what connectors are available:
+
+```tsx
+import { useConnectors } from "@dev-fastn-ai/react-core";
+
+function ConnectorList() {
+  const { data: connectors, isLoading, error } = useConnectors();
+
+  if (isLoading) return <div>Loading available integrations...</div>;
+  if (error) return <div>Error loading connectors: {error.message}</div>;
+
+  return (
+    <div className="connector-grid">
+      <h2>Available Integrations</h2>
+      {connectors?.map((connector) => (
+        <div key={connector.id} className="connector-card">
+          <img src={connector.imageUri} alt={connector.name} />
+          <h3>{connector.name}</h3>
+          <p>{connector.description}</p>
+
+          {connector.status === "ACTIVE" && (
+            <span className="status-badge connected">Connected</span>
+          )}
+
+          {connector.actions?.map((action) => (
+            <button
+              key={action.name}
+              onClick={action.onClick}
+              className={`action-btn ${action.actionType.toLowerCase()}`}
+            >
+              {action.name}
+            </button>
+          ))}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+#### Step 2: List Configurations After Connector Activation
+
+After a connector is activated, you can list its configurations:
 
 ```tsx
-import { useConfigurations } from "@fastn-ai/react-core";
+import { useConfigurations } from "@dev-fastn-ai/react-core";
 
-function ConfigurationsList({ configurationId }: { configurationId: string }) {
-  const { data: configurations, isLoading, error } = useConfigurations({
-    configurationId,
-    status: "ALL", // 'ENABLED' | 'DISABLED' | 'ALL'
-  });
+function ConfigurationList({ configurationId }) {
+  const {
+    data: configurations,
+    isLoading,
+    error,
+  } = useConfigurations({ configurationId });
+  const [selectedConfig, setSelectedConfig] = useState(null);
 
-  if (isLoading) return <div>Loading...</div>;
+  if (isLoading) return <div>Loading configurations...</div>;
   if (error) return <div>Error: {error.message}</div>;
 
   return (
-    <ul>
+    <div className="configuration-list">
+      <h2>Your Integrations</h2>
       {configurations?.map((config) => (
-        <li key={config.id}>{config.name}</li>
+        <div key={config.id} className="config-card">
+          <div className="config-info">
+            <img src={config.imageUri} alt={config.name} />
+            <div>
+              <h3>{config.name}</h3>
+              <p>{config.description}</p>
+            </div>
+          </div>
+
+          <div className="config-actions">
+            {config.status === "ENABLED" && (
+              <span className="status-badge enabled">Active</span>
+            )}
+
+            {config.actions?.map((action) => (
+              <button
+                key={action.name}
+                onClick={async () => {
+                  const result = await action.onClick();
+                  if (
+                    action.actionType === "ENABLE" &&
+                    result?.status === "SUCCESS"
+                  ) {
+                    // Show configuration form for new setup
+                    setSelectedConfig(config);
+                  } else if (
+                    action.actionType === "UPDATE" &&
+                    result?.status === "SUCCESS"
+                  ) {
+                    // Show configuration form for editing
+                    setSelectedConfig(config);
+                  }
+                }}
+                className={`action-btn ${action.actionType.toLowerCase()}`}
+              >
+                {action.name}
+              </button>
+            ))}
+          </div>
+        </div>
       ))}
-    </ul>
+
+      {selectedConfig && (
+        <ConfigurationForm
+          configurationId={selectedConfig.id}
+          onClose={() => setSelectedConfig(null)}
+        />
+      )}
+    </div>
   );
 }
 ```
 
-#### Types
+#### Step 3: Load Configuration Form
 
-```ts
-interface Configuration {
-  id: string;
-  connectorId: string;
-  configurationId: string;
-  name: string;
-  flowId: string;
-  description: string;
-  imageUri: string;
-  status: string;
-  actions: ConfigurationAction[];
-  metadata?: unknown;
-}
+When a configuration is selected (either for new setup or editing), show the configuration form:
 
-interface ConfigurationAction {
-  name: string;
-  actionType: ConfigurationActionType;
-  onClick?: () => Promise<ConnectorActionResult>;
-  form?: ConnectorForm | null;
-  onSubmit?: (formData: unknown) => Promise<ConnectorActionResult>;
-}
+```tsx
+import { useConfigurationForm } from "@dev-fastn-ai/react-core";
 
-type ConfigurationActionType =
-  | ConnectorActionType.ENABLE
-  | ConnectorActionType.DISABLE
-  | ConnectorActionType.DELETE;
+function ConfigurationForm({ configurationId, onClose }) {
+  const {
+    data: configurationForm,
+    isLoading,
+    error,
+    handleSubmit,
+  } = useConfigurationForm({ configurationId });
+
+  const [formData, setFormData] = useState({});
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  // Pre-populate form with existing values if editing
+  useEffect(() => {
+    if (configurationForm?.fields) {
+      const initialData = {};
+      configurationForm.fields.forEach((field) => {
+        if (field.initialValue !== undefined) {
+          initialData[field.key] = field.initialValue;
+        }
+      });
+      setFormData(initialData);
+    }
+  }, [configurationForm]);
+
+  if (isLoading) return <div>Loading configuration form...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  const onSubmit = async (e) => {
+    e.preventDefault();
+    setIsSubmitting(true);
+
+    try {
+      await handleSubmit({ formData });
+      console.log("Configuration saved successfully!");
+      onClose();
+    } catch (error) {
+      console.error("Failed to save configuration:", error);
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
+  return (
+    <div className="modal">
+      <form onSubmit={onSubmit} className="configuration-form">
+        <h2>Configure {configurationForm.name}</h2>
+        <p>{configurationForm.description}</p>
+
+        {configurationForm.fields.map((field) => (
+          <FormField
+            key={field.key}
+            field={field}
+            value={formData[field.key]}
+            onChange={(value) =>
+              setFormData((prev) => ({ ...prev, [field.key]: value }))
+            }
+          />
+        ))}
+
+        <div className="form-actions">
+          <button type="button" onClick={onClose}>
+            Cancel
+          </button>
+          <button type="submit" disabled={isSubmitting}>
+            {isSubmitting ? "Saving..." : "Save Configuration"}
+          </button>
+        </div>
+      </form>
+    </div>
+  );
+}
 ```
 
----
+### **Workflow 2: Managing Existing Configurations**
 
-### 3. Dynamic Configuration Forms
+Now let's show how to manage existing configurations - viewing, editing, and disabling them.
 
-Use the `useConfigurationForm` hook to fetch a configuration form for a connector or configuration. Render the form fields as needed.
+#### Step 1: List Existing Configurations
 
 ```tsx
-import { useConfigurationForm } from "@fastn-ai/react-core";
+import { useConfigurations } from "@dev-fastn-ai/react-core";
 
-function ConfigurationForm({ configurationId }: { configurationId: string }) {
-  const { data: configurationForm, isLoading, error } = useConfigurationForm({ configurationId });
+function ConfigurationManager({ configurationId }) {
+  const {
+    data: configurations,
+    isLoading,
+    error,
+  } = useConfigurations({ configurationId });
+  const [selectedConfig, setSelectedConfig] = useState(null);
 
-  if (isLoading) return <div>Loading...</div>;
+  if (isLoading) return <div>Loading your integrations...</div>;
   if (error) return <div>Error: {error.message}</div>;
 
   return (
-    <form onSubmit={/* your submit handler */}>
-      {configurationForm.fields.map((field) => (
-        // Render field based on type (see below for select and Google Drive picker fields)
+    <div className="configuration-manager">
+      <h2>Your Integrations</h2>
+
+      {configurations?.map((config) => (
+        <div key={config.id} className="config-card">
+          <div className="config-info">
+            <img src={config.imageUri} alt={config.name} />
+            <div>
+              <h3>{config.name}</h3>
+              <p>{config.description}</p>
+            </div>
+          </div>
+
+          <div className="config-actions">
+            {config.status === "ENABLED" && (
+              <span className="status-badge enabled">Active</span>
+            )}
+
+            {config.actions?.map((action) => (
+              <button
+                key={action.name}
+                onClick={async () => {
+                  const result = await action.onClick();
+                  if (
+                    action.actionType === "UPDATE" &&
+                    result?.status === "SUCCESS"
+                  ) {
+                    setSelectedConfig(config);
+                  }
+                }}
+                className={`action-btn ${action.actionType.toLowerCase()}`}
+              >
+                {action.name}
+              </button>
+            ))}
+          </div>
+        </div>
       ))}
-      <button type="submit">Submit</button>
-    </form>
+
+      {selectedConfig && (
+        <ConfigurationForm
+          configurationId={selectedConfig.id}
+          onClose={() => setSelectedConfig(null)}
+        />
+      )}
+    </div>
   );
 }
 ```
 
-#### Types
+#### Step 2: Disable Configuration
 
-```ts
-interface ConfigurationForm {
-  name: string;
-  description: string;
-  imageUri: string;
-  fields: ConnectorField[];
-  submitHandler: (formData: unknown) => Promise<void>;
-}
+```tsx
+function ConfigActions({ config }) {
+  const handleDisable = async (action) => {
+    if (action.actionType === "DISABLE") {
+      const result = await action.onClick();
+      if (result?.status === "SUCCESS") {
+        console.log("Configuration disabled successfully");
+        // Refresh the configuration list
+      }
+    }
+  };
 
-interface ConnectorField {
-  name: string;
-  label: string;
-  type: string; // e.g. 'text', 'select', etc.
-  required?: boolean;
-  options?: Array<{ label: string; value: string }>;
-  // ...other field properties
+  return (
+    <div className="config-actions">
+      {config.actions?.map((action) => (
+        <button
+          key={action.name}
+          onClick={() => handleDisable(action)}
+          className={`action-btn ${action.actionType.toLowerCase()}`}
+        >
+          {action.name}
+        </button>
+      ))}
+    </div>
+  );
 }
 ```
 
----
+#### Step 3: Form Field Value Handling
+
+The form fields handle different value types based on the field type:
 
-### 4. Advanced Field Handling: Select & Google Drive File Picker
+- **Select fields**: Always return `{ label: string, value: string }` objects
+- **Multi-select fields**: Always return `{ label: string, value: string }[]` arrays
+- **Google Drive picker fields**: Always return `{ label: string, value: string }` objects or arrays
+- **Other fields**: Return primitive values (string, number, boolean)
 
-#### Select Fields (Single & Multi-Select)
+```tsx
+// Example form data structure
+const formData = {
+  // Select field - single object
+  channel: { label: "General", value: "C123456" },
+
+  // Multi-select field - array of objects
+  channels: [
+    { label: "General", value: "C123456" },
+    { label: "Random", value: "C789012" },
+  ],
+
+  // Google Drive picker - single object
+  folder: { label: "My Documents", value: "folder_id_123" },
+
+  // Google Drive picker multi - array of objects
+  files: [
+    { label: "document1.pdf", value: "file_id_1" },
+    { label: "document2.pdf", value: "file_id_2" },
+  ],
+
+  // Text field - primitive
+  webhookUrl: "https://hooks.slack.com/...",
+
+  // Boolean field - primitive
+  enableNotifications: true,
+};
+```
 
-For fields of type `select` or `multi-select`, use the `useFieldOptions` hook to fetch options, handle search, pagination, and errors. This abstracts away the complexity of loading options from remote sources.
+---
 
-**Example: Generic SelectField Component**
+## 🎨 Form Field Components
+
+### **Select and Multi-Select Fields**
+
+For fields of type `select` or `multi-select`, use the `useFieldOptions` hook to handle dynamic options loading. These fields always work with `{ label, value }` objects:
 
 ```tsx
-import { useFieldOptions } from "@fastn-ai/react-core";
+import { useFieldOptions } from "@dev-fastn-ai/react-core";
 
 function SelectField({ field, value, onChange, isMulti = false }) {
   const {
@@ -268,7 +624,6 @@ function SelectField({ field, value, onChange, isMulti = false }) {
     loadMore,
     error,
     search,
-    refresh,
     totalLoadedOptions,
   } = useFieldOptions(field);
 
@@ -280,75 +635,105 @@ function SelectField({ field, value, onChange, isMulti = false }) {
     if (hasNext && !loadingMore) loadMore();
   }
 
-  function handleRefresh() {
-    refresh();
+  function handleSelectChange(selectedOptions) {
+    if (isMulti) {
+      // For multi-select, value should be an array of { label, value } objects
+      const selectedValues = selectedOptions.map((option) => ({
+        label: option.label,
+        value: option.value,
+      }));
+      onChange(selectedValues);
+    } else {
+      // For single select, value should be a single { label, value } object
+      const selectedValue = selectedOptions[0]
+        ? {
+            label: selectedOptions[0].label,
+            value: selectedOptions[0].value,
+          }
+        : null;
+      onChange(selectedValue);
+    }
   }
 
   return (
-    <div>
-      <label>{field.label}{field.required && ' *'}</label>
+    <div className="field-container">
+      <label className="field-label">
+        {field.label}
+        {field.required && <span className="required"> *</span>}
+      </label>
+
       {error && (
-        <div>
-          <span style={{ color: 'red' }}>Error loading options</span>
-          <button type="button" onClick={handleRefresh}>Retry</button>
+        <div className="error-message">
+          Error loading options: {error.message}
         </div>
       )}
+
       <input
         type="text"
         placeholder={field.placeholder || `Search ${field.label}`}
         onChange={handleInputChange}
         disabled={loading}
+        className="search-input"
       />
+
       <select
         multiple={isMulti}
-        value={value}
-        onChange={e => {
+        value={isMulti ? (value || []).map((v) => v.value) : value?.value || ""}
+        onChange={(e) => {
           if (isMulti) {
-            const selected = Array.from(e.target.selectedOptions, o => o.value);
-            onChange(selected);
+            const selectedOptions = Array.from(e.target.selectedOptions).map(
+              (option) => {
+                const opt = options.find((o) => o.value === option.value);
+                return { label: opt.label, value: opt.value };
+              }
+            );
+            handleSelectChange(selectedOptions);
           } else {
-            onChange(e.target.value);
+            const selectedOption = options.find(
+              (o) => o.value === e.target.value
+            );
+            handleSelectChange(selectedOption ? [selectedOption] : []);
           }
         }}
         disabled={loading}
+        className="select-field"
       >
-        {options.map(opt => (
-          <option key={opt.value} value={opt.value}>{opt.label}</option>
+        {options.map((opt) => (
+          <option key={opt.value} value={opt.value}>
+            {opt.label}
+          </option>
         ))}
       </select>
-      {loading && <div>Loading options...</div>}
+
+      {loading && <div className="loading">Loading options...</div>}
+
       {hasNext && !loadingMore && (
-        <button type="button" onClick={handleLoadMore}>Load More</button>
+        <button
+          type="button"
+          onClick={handleLoadMore}
+          className="load-more-btn"
+        >
+          Load More
+        </button>
+      )}
+
+      {loadingMore && <div className="loading">Loading more...</div>}
+
+      <div className="options-info">
+        Loaded {totalLoadedOptions} options{hasNext ? "" : " (all loaded)"}
+      </div>
+
+      {field.description && (
+        <div className="field-description">{field.description}</div>
       )}
-      {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>
   );
 }
 ```
 
-**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 Picker Fields**
 
-#### Google Drive File Picker Field
-
-For fields requiring Google Drive file selection, the field type will be `google-files-picker-select` or similar. These fields provide an `optionsSource` with a method to open the Google Files Picker dialog.
-
-**Example: GoogleFilesPickerField Component**
+For Google Drive file picker fields, handle the file selection flow. These fields also work with `{ label, value }` objects:
 
 ```tsx
 function GoogleFilesPickerField({ field, value, onChange, isMulti = false }) {
@@ -357,27 +742,47 @@ function GoogleFilesPickerField({ field, value, onChange, isMulti = false }) {
       await field.optionsSource.openGoogleFilesPicker({
         onComplete: async (files) => {
           if (isMulti) {
-            onChange(files);
+            // For multi-select, ensure we have an array of { label, value } objects
+            const formattedFiles = files.map((file) => ({
+              label: file.label || file.name || file.value,
+              value: file.value || file.id,
+            }));
+            onChange(formattedFiles);
           } else {
-            onChange(files[0]);
+            // For single select, ensure we have a single { label, value } object
+            const formattedFile = {
+              label: files[0]?.label || files[0]?.name || files[0]?.value,
+              value: files[0]?.value || files[0]?.id,
+            };
+            onChange(formattedFile);
           }
         },
         onError: async (pickerError) => {
-          alert('Google Files Picker error: ' + pickerError);
+          console.error("Google Files Picker error:", pickerError);
+          alert("Failed to pick files: " + pickerError);
         },
       });
     }
   }
 
   return (
-    <div>
-      <label>{field.label}{field.required && ' *'}</label>
-      <button type="button" onClick={handlePickFiles}>
+    <div className="field-container">
+      <label className="field-label">
+        {field.label}
+        {field.required && <span className="required"> *</span>}
+      </label>
+
+      <button
+        type="button"
+        onClick={handlePickFiles}
+        className="google-picker-btn"
+      >
         Pick from Google Drive
       </button>
+
       {value && (
-        <div>
-          <strong>Selected file{isMulti ? 's' : ''}:</strong>
+        <div className="selected-files">
+          <strong>Selected file{isMulti ? "s" : ""}:</strong>
           <ul>
             {(isMulti ? value : [value]).map((file, idx) => (
               <li key={file.value || idx}>{file.label || file.value}</li>
@@ -385,66 +790,264 @@ function GoogleFilesPickerField({ field, value, onChange, isMulti = false }) {
           </ul>
         </div>
       )}
-      {field.description && <div style={{ fontSize: 'smaller', color: '#666' }}>{field.description}</div>}
+
+      {field.description && (
+        <div className="field-description">{field.description}</div>
+      )}
     </div>
   );
 }
 ```
 
-**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;
+### **Generic Form Field Component**
+
+Create a reusable component that handles different field types with proper value handling:
+
+```tsx
+function FormField({ field, value, onChange }) {
+  switch (field.type) {
+    case "text":
+    case "email":
+    case "password":
+    case "number":
+      return (
+        <div className="field-container">
+          <label className="field-label">
+            {field.label}
+            {field.required && <span className="required"> *</span>}
+          </label>
+          <input
+            type={field.type}
+            value={value || ""}
+            onChange={(e) => onChange(e.target.value)}
+            placeholder={field.placeholder}
+            disabled={field.disabled}
+            className="text-input"
+          />
+          {field.description && (
+            <div className="field-description">{field.description}</div>
+          )}
+        </div>
+      );
+
+    case "checkbox":
+      return (
+        <div className="field-container">
+          <label className="field-label">
+            <input
+              type="checkbox"
+              checked={value || false}
+              onChange={(e) => onChange(e.target.checked)}
+              disabled={field.disabled}
+              className="checkbox-input"
+            />
+            {field.label}
+            {field.required && <span className="required"> *</span>}
+          </label>
+          {field.description && (
+            <div className="field-description">{field.description}</div>
+          )}
+        </div>
+      );
+
+    case "select":
+      return (
+        <SelectField
+          field={field}
+          value={value}
+          onChange={onChange}
+          isMulti={false}
+        />
+      );
+
+    case "multi-select":
+      return (
+        <SelectField
+          field={field}
+          value={value}
+          onChange={onChange}
+          isMulti={true}
+        />
+      );
+
+    case "google-files-picker-select":
+      return (
+        <GoogleFilesPickerField
+          field={field}
+          value={value}
+          onChange={onChange}
+          isMulti={false}
+        />
+      );
+
+    case "google-files-picker-multi-select":
+      return (
+        <GoogleFilesPickerField
+          field={field}
+          value={value}
+          onChange={onChange}
+          isMulti={true}
+        />
+      );
+
+    default:
+      return (
+        <div className="field-container">
+          <label className="field-label">
+            {field.label} (Unsupported type: {field.type})
+          </label>
+        </div>
+      );
+  }
 }
 ```
 
-**Integration Tips:**
-- Use these fields as controlled components in your form library (Formik, React Hook Form, etc.).
-- Manage `value` and `onChange` via your form state.
-- Combine with other input types to build a complete dynamic configuration form.
-
 ---
 
-## Error Handling & Troubleshooting
+### **Error Handling and Loading States**
+
+```tsx
+function ConnectorManager() {
+  const { data: connectors, isLoading, error, refetch } = useConnectors();
+  const [retryCount, setRetryCount] = useState(0);
+
+  const handleRetry = () => {
+    setRetryCount((prev) => prev + 1);
+    refetch();
+  };
+
+  if (isLoading) {
+    return (
+      <div className="loading-container">
+        <div className="spinner"></div>
+        <p>Loading your integrations...</p>
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <div className="error-container">
+        <h3>Failed to load integrations</h3>
+        <p>{error.message}</p>
+        <button onClick={handleRetry} className="retry-btn">
+          Retry ({retryCount} attempts)
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="connector-list">
+      {connectors?.map((connector) => (
+        <ConnectorCard key={connector.id} connector={connector} />
+      ))}
+    </div>
+  );
+}
+```
+
+```tsx
+function ConfigurationActions({ config }) {
+  const queryClient = useQueryClient();
+
+  const handleAction = async (action) => {
+    // Optimistically update the UI
+    queryClient.setQueryData(["configurations"], (oldData) => {
+      return oldData?.map((c) =>
+        c.id === config.id
+          ? {
+              ...c,
+              status: action.actionType === "ENABLE" ? "ENABLED" : "DISABLED",
+            }
+          : c
+      );
+    });
+
+    try {
+      const result = await action.onClick();
+      if (result?.status === "SUCCESS") {
+        // Invalidate and refetch to ensure consistency
+        queryClient.invalidateQueries(["configurations"]);
+      }
+    } catch (error) {
+      // Revert optimistic update on error
+      queryClient.invalidateQueries(["configurations"]);
+      console.error("Action failed:", error);
+    }
+  };
 
-- **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.
+  return (
+    <div className="config-actions">
+      {config.actions?.map((action) => (
+        <button
+          key={action.name}
+          onClick={() => handleAction(action)}
+          className={`action-btn ${action.actionType.toLowerCase()}`}
+        >
+          {action.name}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
 
 ---
 
-## TypeScript Support
+## 🚨 Troubleshooting
+
+### **Common Issues**
 
-All hooks and data structures are fully typed. You can import types directly:
+1. **"Invalid tenant ID" error**
 
-```ts
-import type { Connector, Configuration, ConnectorAction, ConfigurationAction } from '@fastn-ai/react-core';
+   - Ensure your `tenantId` is a valid string and matches your user/organization identifier
+   - Check that the tenant has proper permissions in your Fastn space
+
+2. **"Space not found" error**
+
+   - Verify your `spaceId` is correct
+   - Ensure your auth token has access to the specified space
+
+3. **Configuration form not loading**
+
+   - Check that the `configurationId` is valid and exists
+   - Ensure the connector is properly activated before trying to configure it
+
+4. **Google Drive picker not working**
+   - Verify Google Drive connector is properly configured in your Fastn space
+   - Check that the user has granted necessary permissions
+
+### **Debug Mode**
+
+Enable debug logging to troubleshoot issues:
+
+```tsx
+const fastnConfig = {
+  environment: "LIVE",
+  authToken: "your-auth-token",
+  tenantId: "your-tenant-id",
+  spaceId: "your-space-id",
+  debug: true, // Enable debug logging
+};
 ```
 
 ---
 
-## License
+## 📚 Additional Resources
 
-MIT License. See the [LICENSE](LICENSE) file for details.
+- [Fastn.ai Documentation](https://docs.fastn.ai/)
+- [React Query Documentation](https://tanstack.com/query/latest)
+- [Fastn Community](https://community.fastn.ai/)
 
 ---
 
-## Support
+## 🤝 Contributing
 
-- Email: support@fastn.ai
-- Documentation: [https://docs.fastn.ai](https://docs.fastn.ai)
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
 
 ---
 
-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. 
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.