Configuration

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

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.

await initializeAiChatExtensionSdk('your-api-key', {
  // ... options
});

Contact [email protected] to receive your API key.

Configuration options

featureControls

Control which SDK features are enabled.

featureControls?: {
  enableChatBadge?: boolean;   // Default: false
  enableChatPanel?: boolean;   // Default: false
}

Example:

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

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

platformControls

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

platformControls?: {
  enableGoogle?: boolean;   // Default: true
  enableChatGPT?: boolean;  // Default: false
}

Example:

platformControls: {
  enableGoogle: true,   // Enable on Google Search
  enableChatGPT: false, // Disable on ChatGPT
}

Supported platforms:

Google Search: google.com
ChatGPT: chatgpt.com

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

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

chatConfig

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

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:

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.

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:

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:

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'
  };
}

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

Example:

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.

dataProviders?: {
  offerRedirectUrlProvider?: OfferRedirectUrlProvider;
  merchantCashbackProvider?: MerchantCashbackProvider;
}

Type definitions:

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:

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
    }
  },
}

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

See the Data Providers guide for detailed implementation examples.

enableDebug

Enable detailed console logging for debugging.

enableDebug?: boolean;  // Default: false

Example:

enableDebug: true,  // Enable console.log statements from SDK

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

skipManifestValidation

Skip automatic validation of manifest.json configuration.

skipManifestValidation?: boolean;  // Default: true

Example:

skipManifestValidation: false,  // Enable validation (recommended for development)

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

Complete configuration example

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

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:

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

await initializeAiChatExtensionSdk(apiKey, config);

AI Chat Extension SDK Reference

​Overview

​Initialization signature

​Required parameters

​apiKey

​Configuration options

​featureControls

​platformControls

​chatConfig

​badgeConfig

​Layout configuration

​dataProviders

​enableDebug

​skipManifestValidation

​Complete configuration example

​Environment-specific configuration

Overview

Initialization signature

Required parameters

apiKey

Configuration options

featureControls

platformControls

chatConfig

badgeConfig

Layout configuration

dataProviders

enableDebug

skipManifestValidation

Complete configuration example

Environment-specific configuration