@ai-ad-network/frontend-sdk 1.0.0

package/README.md

@@ -0,0 +1,272 @@
+# AI Ad Network Frontend SDK
+
+> React SDK for displaying native, AI-powered ads in your application
+
+## Features
+
+- 🎯 **Intent-based Ad Delivery** - Ads matched to user intent
+- 🎨 **Native Ad Formats** - Action Cards, Suffix, Follow-up, Sponsored Sources
+- 📊 **Built-in Analytics** - Impression and click tracking
+- ⚡ **Optimized Performance** - SWR caching, Intersection Observer
+- 🎭 **Headless Design** - Full customization with CSS variables
+- 📱 **Responsive** - Works on all screen sizes
+- 🔐 **Built-in Authentication** - API key support for secure access
+
+## Installation
+
+```bash
+npm install @ai-ad-network/frontend-sdk
+# or
+yarn add @ai-ad-network/frontend-sdk
+# or
+pnpm add @ai-ad-network/frontend-sdk
+```
+
+## Quick Start
+
+```tsx
+import { AdProvider, useAiAds, ActionCardAd } from '@ai-ad-network/frontend-sdk';
+
+function App() {
+  return (
+    <AdProvider
+      config={{
+        apiBaseUrl: 'https://your-ad-network.com/api/v1',
+        apiKey: 'ak_your_tenant_your_key', // Get from admin
+        debug: process.env.NODE_ENV === 'development',
+      }}
+    >
+      <ChatApp />
+    </AdProvider>
+  );
+}
+
+function ChatApp() {
+  const [query, setQuery] = useState('');
+  const [response, setResponse] = useState('');
+  const [isFinished, setIsFinished] = useState(false);
+
+  const { ads, isLoading } = useAiAds(query, response, isFinished, {
+    formats: ['action_card', 'suffix'],
+    placement: 'post_response',
+  });
+
+  return (
+    <div>
+      {/* Your chat UI */}
+      {ads.map(ad => (
+        <ActionCardAd key={ad.id} ad={ad} />
+      ))}
+    </div>
+  );
+}
+```
+
+## Configuration
+
+### AdProvider Props
+
+```tsx
+<AdProvider
+  config={{
+    // API Configuration
+    apiBaseUrl?: string;        // Default: '/api/v1'
+    apiKey?: string;             // Your API key (format: ak_tenant_key)
+
+    // Ad Behavior
+    defaultFormats?: string[];   // Default: ['action_card', 'suffix']
+    defaultPlacement?: string;   // Default: 'post_response'
+    enabled?: boolean;           // Default: true
+
+    // Debugging
+    debug?: boolean;             // Default: false
+    headers?: Record<string, string>;
+
+    // Performance
+    timeout?: number;            // Default: 5000
+    maxRetries?: number;         // Default: 2
+
+    // Tracking
+    userId?: string;
+  }}
+>
+  {children}
+</AdProvider>
+```
+
+## Components
+
+### ActionCardAd
+
+Rich media card for product ads.
+
+```tsx
+<ActionCardAd
+  ad={ad}
+  variant="horizontal" // 'horizontal' | 'vertical' | 'compact'
+  onClick={() => console.log('Clicked!')}
+/>
+```
+
+### SuffixAd
+
+Text-based ad appended to AI responses.
+
+```tsx
+<SuffixAd
+  ad={ad}
+  aiContext={aiResponse}
+  variant="block" // 'block' | 'inline' | 'minimal'
+/>
+```
+
+### FollowUpAd
+
+Ad disguised as a follow-up question.
+
+```tsx
+<FollowUpAd
+  ad={ad}
+  variant="bubble" // 'bubble' | 'pill' | 'underline'
+/>
+
+// Or mix with regular questions
+<FollowUpAdMixed
+  questions={['How does it work?', 'What are the features?']}
+  ad={ad}
+  adPosition={1}
+  onQuestionClick={(q) => console.log(q)}
+/>
+```
+
+### SponsoredSource
+
+Ad in citation/source list format.
+
+```tsx
+<SponsoredSource
+  ad={ad}
+  variant="card" // 'card' | 'list-item' | 'minimal'
+/>
+
+// Or mix with regular sources
+<SourceListWithAds
+  sources={[{ title: 'Wikipedia', url: '...' }]}
+  ad={ad}
+  adPosition={1}
+/>
+```
+
+## Hooks
+
+### useAiAds
+
+Main hook for fetching ads.
+
+```tsx
+const {
+  ads,           // Array of KoahAd objects
+  intent,        // Intent analysis result
+  routing,       // Routing information
+  isLoading,     // Loading state
+  error,         // Error object
+  refetch,       // Manual refetch function
+} = useAiAds(
+  userQuery,      // User's question
+  aiResponse,     // AI's response
+  isStreamFinished, // Boolean
+  {
+    enabled: true,
+    formats: ['action_card', 'suffix'],
+    placement: 'post_response',
+    apiBaseUrl: '/api/v1',
+  }
+);
+```
+
+### useAdTracking
+
+Tracking hook for impressions and clicks.
+
+```tsx
+const {
+  impressionRef,   // Ref to attach to ad element
+  handleClick,     // Click handler
+  hasImpressed,    // Boolean
+  isIntersecting,  // Boolean
+} = useAdTracking(ad, {
+  intersectionThreshold: 0.5,
+  minViewTimeMs: 1000,
+  onClick: () => console.log('Clicked'),
+  onImpression: () => console.log('Viewed'),
+});
+```
+
+## Styling
+
+### CSS Variables
+
+Customize the appearance with CSS variables:
+
+```css
+:root {
+  --ad-primary: #3b82f6;
+  --ad-secondary: #8b5cf6;
+  --ad-background: #f8fafc;
+  --ad-border: #e2e8f0;
+  --ad-text: #1e293b;
+  --ad-sponsored: #94a3b8;
+}
+```
+
+### Utility Function
+
+Use the `cn` function for conditional classes:
+
+```tsx
+import { cn } from '@ai-ad-network/frontend-sdk';
+
+<div className={cn(
+  'base-class',
+  isActive && 'active-class',
+  'more-classes'
+)} />
+```
+
+## TypeScript Support
+
+Full TypeScript support with exported types:
+
+```tsx
+import type {
+  KoahAd,
+  IntentResult,
+  AdFormat,
+  AdSource,
+  RoutingInfo,
+} from '@ai-ad-network/frontend-sdk';
+```
+
+## Integration Guide
+
+For detailed Chatbox integration instructions, see [CHATBOX_INTEGRATION.md](./CHATBOX_INTEGRATION.md).
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run Storybook
+npm run storybook
+
+# Build library
+npm run build
+
+# Run demo app
+cd demo-app && npm run dev
+```
+
+## License
+
+MIT