> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onsleek.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Complete reference for SDK configuration options

## Overview

The AI Chat Extension SDK provides extensive configuration options to control features, customize appearance, and integrate with your data sources. All configuration is passed during SDK initialization.

## Initialization signature

```typescript theme={null}
function initializeAiChatExtensionSdk(
  apiKey: string,
  options?: Partial<AiChatExtensionSdkOptions>,
  listeners?: AiChatExtensionSdkEventListener[]
): Promise<AiChatExtensionSdk>
```

## Required parameters

### apiKey

**Type**: `string`

Your Pie AI API key for authentication with the chat and query classification services.

```typescript theme={null}
await initializeAiChatExtensionSdk('your-api-key', {
  // ... options
});
```

<Note>
  Contact [support@onsleek.org](mailto:support@onsleek.org) to receive your API key.
</Note>

## Configuration options

### featureControls

Control which SDK features are enabled.

```typescript theme={null}
featureControls?: {
  enableChatBadge?: boolean;   // Default: false
  enableChatPanel?: boolean;   // Default: false
}
```

**Example**:

```typescript theme={null}
featureControls: {
  enableChatBadge: true,  // Show floating badge with suggested prompts
  enableChatPanel: true,  // Allow users to open full chat panel
}
```

<Accordion title="Use cases">
  * **Query classification only**: Set both to `false` to only classify queries and emit events
  * **Badge only**: Enable badge to show prompts without full chat capability
  * **Full experience**: Enable both for complete AI chat functionality
</Accordion>

### platformControls

Control which platforms the SDK is enabled on. URL match patterns are handled internally based on these settings.

```typescript theme={null}
platformControls?: {
  enableGoogle?: boolean;   // Default: true
  enableChatGPT?: boolean;  // Default: false
}
```

**Example**:

```typescript theme={null}
platformControls: {
  enableGoogle: true,   // Enable on Google Search
  enableChatGPT: false, // Disable on ChatGPT
}
```

**Supported platforms**:

* **Google Search**: google.com
* **ChatGPT**: chatgpt.com

<Accordion title="Platform-specific behavior">
  - When `enableGoogle` is `true`, the SDK will run on Google Search pages
  - When `enableChatGPT` is `true`, the SDK will run on ChatGPT conversation pages
  - You can enable both platforms simultaneously
  - By default, only Google Search is enabled
</Accordion>

<Note>
  Platform controls work independently from feature controls. You can enable platforms without enabling UI features to use query classification only.
</Note>

### chatConfig

Configure the chat panel behavior, AI backend, and appearance.

```typescript theme={null}
chatConfig?: {
  apiBaseUrl?: string;               // Override API base URL (default: https://chat.pie.org)
  isFloating?: boolean;              // Apply floating panel styles (default: true)
  messageLimitPerThread?: number;    // Max messages per conversation

  content?: {
    header?: {                       // Falls back to brand config if not provided
      logoUrl?: string;              // Logo URL for the chat header (height: 36px, falls back to brand.logoUrl)
      name?: string;                 // Brand/product name in the header (falls back to brand.name)
    };
    defaultPrompts?: string[];       // Default suggested prompts
    disclaimerText?: string;         // Custom disclaimer text
    excludeProviderAttribution?: boolean;
    error?: { message?: string };
    input?: { placeholder?: string };
    intro?: { message?: string; title?: string };
    loading?: { messages?: string[] };
    rateLimit?: { message?: string };
    reload?: { action?: string; message?: string };
  };

  assistant?: {
    name?: string;                   // AI assistant name
    description?: string;            // AI assistant description
    settingsUrl?: string;            // Link to settings page
  };

  brand?: {
    logoUrl?: string;                // Panel logo URL
    name?: string;                   // Brand name
  };

  styling?: {
    primaryColor?: string;           // Primary color for light mode
    primaryColorDarkMode?: string;   // Primary color for dark mode
    colorMode?: 'light' | 'dark' | 'system';  // Default: 'system'
  };

  layout?: LayoutConfig;             // Panel position and size
}
```

**Example**:

```typescript theme={null}
chatConfig: {
  messageLimitPerThread: 50,
  content: {
    header: {
      logoUrl: 'https://your-extension.com/header-logo.png',
      name: 'Your Brand',
    },
    disclaimerText: 'AI responses may not always be accurate',
    defaultPrompts: ['Find me the best deals', 'Compare prices'],
    input: { placeholder: 'Ask me anything...' },
    intro: { title: 'Welcome!', message: 'How can I help you today?' },
  },
  assistant: {
    name: 'Shopping Assistant',
    description: 'Your AI-powered shopping helper',
  },
  brand: {
    logoUrl: 'https://your-extension.com/logo.png',
    name: 'Your Brand',
  },
  styling: {
    primaryColor: '#5C59FE',
    primaryColorDarkMode: '#8B87FF',
    colorMode: 'system',
  },
}
```

### badgeConfig

Configure the chat badge behavior and appearance.

```typescript theme={null}
badgeConfig?: {
  allowExpand?: boolean;             // Allow badge expansion on hover (default: true)
  autoCollapse?: boolean;            // Auto-collapse after delay (default: true)

  content?: {
    badge?: { text?: string };       // Badge text content
    onboarding?: {
      title?: string;                // Onboarding title
      description?: string;          // Onboarding description
    };
  };

  assistant?: {
    name?: string;                   // AI assistant name
    description?: string;            // AI assistant description
    settingsUrl?: string;            // Link to settings page
  };

  brand?: {
    logoUrl?: string;                // Badge logo URL
    name?: string;                   // Brand name
  };

  styling?: {
    primaryColor?: string;           // Primary color for light mode
    primaryColorDarkMode?: string;   // Primary color for dark mode
    colorMode?: 'light' | 'dark' | 'system';  // Default: 'system'
  };

  layout?: LayoutConfig;             // Badge position and size
}
```

**Example**:

```typescript theme={null}
badgeConfig: {
  allowExpand: true,
  autoCollapse: true,
  content: {
    badge: { text: 'Ask AI' },
    onboarding: {
      title: 'Meet your shopping assistant',
      description: 'Get personalized recommendations and deals',
    },
  },
  brand: {
    logoUrl: 'https://your-extension.com/badge-logo.png',
    name: 'Your Brand',
  },
  styling: {
    primaryColor: '#5C59FE',
  },
}
```

### Layout configuration

Both `chatConfig.layout` and `badgeConfig.layout` support position and size configuration:

```typescript theme={null}
interface LayoutConfig {
  position?: {
    top?: string;      // e.g., '0px', '10px', 'unset'
    right?: string;    // e.g., '0px', '20px', 'unset'
    bottom?: string;   // e.g., '0px', '10px', 'unset'
    left?: string;     // e.g., '0px', '20px', 'unset'
  };
  size?: {
    minWidth?: string;   // e.g., '400px', '30vw'
    width?: string;      // e.g., '400px', '30vw'
    maxWidth?: string;   // e.g., '500px', 'none'
    minHeight?: string;  // e.g., '400px'
    height?: string;     // e.g., '100vh', '600px'
    maxHeight?: string;  // e.g., '100vh', 'none'
  };
}
```

<Note>
  Use `chatConfig.isFloating` (defaults to `true`) to control whether floating panel styles (border, border-radius, box shadow) are applied to the chat panel.
</Note>

**Example**:

```typescript theme={null}
chatConfig: {
  layout: {
    position: {
      top: '0px',
      right: '0px',
      bottom: '0px',
    },
    size: {
      width: '400px',
      maxHeight: '100vh',
    },
  },
}
```

### dataProviders

Integrate your offer redirect urls and cashback data into chat conversations. Optional but recommended for monetization.

```typescript theme={null}
dataProviders?: {
  offerRedirectUrlProvider?: OfferRedirectUrlProvider;
  merchantCashbackProvider?: MerchantCashbackProvider;
}
```

**Type definitions**:

```typescript theme={null}
type OfferRedirectUrlProvider = (
  url: string
) => Promise<string | null | undefined> | string | null | undefined;

type MerchantCashbackProvider = (
  merchantUrls: string[]
) => Promise<Record<string, MerchantCashback>> | Record<string, MerchantCashback>;

interface MerchantCashback {
  text: string;  // e.g., "5% cash back", "Up to $10 back"
}
```

**Example**:

```typescript theme={null}
dataProviders: {
  offerRedirectUrlProvider: async (url) => {
    try {
      const response = await fetch(`https://api.example.com/offer-redirect?url=${encodeURIComponent(url)}`);
      const data = await response.json();
      return data.offerRedirectUrl || null;
    } catch (error) {
      console.error('Failed to fetch offer redirect url:', error);
      return null;  // Always return null on error
    }
  },
  merchantCashbackProvider: async (urls) => {
    try {
      const response = await fetch('https://api.example.com/cashback', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ urls }),
      });
      const data = await response.json();
      return data.cashback || {};
    } catch (error) {
      console.error('Failed to fetch cashback:', error);
      return {};  // Always return {} on error
    }
  },
}
```

<Warning>
  Data providers must handle errors gracefully and return `null` (for offer redirect urls) or `{}` (for cashback) on failure. Never throw exceptions.
</Warning>

See the [Data Providers](/sdk/data-providers) guide for detailed implementation examples.

### enableDebug

Enable detailed console logging for debugging.

```typescript theme={null}
enableDebug?: boolean;  // Default: false
```

**Example**:

```typescript theme={null}
enableDebug: true,  // Enable console.log statements from SDK
```

<Note>
  Debug mode should be disabled in production builds to reduce console noise and improve performance.
</Note>

### skipManifestValidation

Skip automatic validation of manifest.json configuration.

```typescript theme={null}
skipManifestValidation?: boolean;  // Default: true
```

**Example**:

```typescript theme={null}
skipManifestValidation: false,  // Enable validation (recommended for development)
```

<Note>
  By default, manifest validation is skipped. Set to `false` during development to validate that your manifest includes required permissions and web-accessible resources.
</Note>

## Complete configuration example

Here's a complete example with all commonly used options:

```typescript theme={null}
import {
  initializeAiChatExtensionSdk,
  type OfferRedirectUrlProvider,
  type MerchantCashbackProvider,
} from '@sleek/ai-chat-extension-sdk';

const offerRedirectUrlProvider: OfferRedirectUrlProvider = async (url) => {
  const response = await fetch(`https://api.example.com/offer-redirect?url=${encodeURIComponent(url)}`);
  const data = await response.json();
  return data.offerRedirectUrl || null;
};

const merchantCashbackProvider: MerchantCashbackProvider = async (urls) => {
  const response = await fetch('https://api.example.com/cashback', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ urls }),
  });
  const data = await response.json();
  return data.cashback || {};
};

await initializeAiChatExtensionSdk('your-api-key', {
  // Feature controls
  featureControls: {
    enableChatBadge: true,
    enableChatPanel: true,
  },

  // Platform controls
  platformControls: {
    enableGoogle: true,
    enableChatGPT: false,
  },

  // Debugging
  enableDebug: process.env.NODE_ENV === 'development',

  // Chat panel configuration
  chatConfig: {
    messageLimitPerThread: 50,
    isFloating: true, // Apply floating panel styles (border, border-radius, box shadow)
    content: {
      header: {
        logoUrl: 'https://your-extension.com/header-logo.png',
        name: 'Your Brand',
      },
      disclaimerText: 'AI responses may contain errors',
      defaultPrompts: ['Find the best deals', 'Compare products'],
      input: { placeholder: 'Ask me anything...' },
      intro: {
        title: 'Welcome!',
        message: 'How can I help you shop smarter today?',
      },
    },
    assistant: {
      name: 'Shopping Assistant',
      description: 'Your AI-powered shopping helper',
    },
    brand: {
      logoUrl: 'https://your-extension.com/logo.png',
      name: 'Your Brand',
    },
    styling: {
      primaryColor: '#5C59FE',
      primaryColorDarkMode: '#8B87FF',
      colorMode: 'system',
      fontFamily: 'Inter, sans-serif',
    },
    layout: {
      position: { top: '0px', right: '0px', bottom: '0px' },
      size: { width: '400px' },
    },
  },

  // Badge configuration
  badgeConfig: {
    allowExpand: true,
    autoCollapse: true,
    content: {
      badge: { text: 'Ask AI' },
      onboarding: {
        title: 'Meet your shopping assistant',
        description: 'Get personalized recommendations and deals',
      },
    },
    brand: {
      logoUrl: 'https://your-extension.com/badge-logo.png',
      name: 'Your Brand',
    },
    styling: {
      primaryColor: '#5C59FE',
    },
  },

  // Data providers (optional)
  dataProviders: {
    offerRedirectUrlProvider,
    merchantCashbackProvider,
  },
});
```

## Environment-specific configuration

For different environments (development, staging, production), use environment variables:

```typescript theme={null}
const config = {
  featureControls: {
    enableChatBadge: true,
    enableChatPanel: true,
  },
  enableDebug: process.env.NODE_ENV === 'development',
  // ... rest of config
};

await initializeAiChatExtensionSdk(apiKey, config);
```