@ai-ad-network/frontend-sdk 1.0.7 → 1.0.9

package/README.md

@@ -2,19 +2,23 @@
 
 > 🚀 **Zero-config** SDK for AI-powered native ads with automatic client info collection
 >
-> 📦 **Dual Support**: React SDK + Universal Framework-Agnostic SDK
+> **📦 Dual Support**: React SDK + Universal Framework-Agnostic SDK
+>
+> **Version**: 1.0.7
+
+---
 
-## 🎯 Choose Your Integration
+## 🎯 Choose Your SDK
 
-### React Projects (Original SDK)
+### React Projects
 ```bash
 npm install @ai-ad-network/frontend-sdk
 ```
 ```tsx
-import { AdProvider, useAiAds } from '@ai-ad-network/frontend-sdk';
+import { AdProvider, useAiAds, ActionCardAd } from '@ai-ad-network/frontend-sdk';
 ```
 
-### Any Other Framework (Universal SDK) ⭐ NEW
+### Other Frameworks (Vue, Angular, Vanilla JS, etc.)
 ```bash
 npm install @ai-ad-network/frontend-sdk
 ```
@@ -22,119 +26,154 @@ npm install @ai-ad-network/frontend-sdk
 import { AdManager, DOMRenderer } from '@ai-ad-network/frontend-sdk/universal';
 ```
 
-**Universal SDK Works With:**
-- ✅ Vanilla JavaScript
-- ✅ Vue 2 & 3
-- ✅ Angular
-- ✅ Svelte
-- ✅ SolidJS
-- ✅ Any other framework
+**Universal SDK Works With**: Vue 2/3, Angular, Svelte, SolidJS, Vanilla JS, or any other framework
 
-📖 **[Universal SDK Guide](./docs/UNIVERSAL_SDK_GUIDE.md)** for non-React frameworks
+---
 
 ## ✨ Key Features
 
 - 🎯 **Intent-based Ad Delivery** - Ads matched to user intent
-- 🎨 **Native Ad Formats** - Action Cards, Suffix, Follow-up, Sponsored Sources
+- 🎨 **Native Ad Formats** - Action Cards, Suffix, Follow-up, Sponsored Sources, Lead Gen
 - 📊 **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
-- 🌐 **OpenRTB Compliant** - ✨ **Zero-config** auto-collection of device/app/user/geo info
+- 🔐 **Built-in Authentication** - API key support
+- 🌐 **OpenRTB Compliant** - **Zero-config** auto-collection of device/app/user/geo info
+- 🌐 **Framework-Agnostic** - Works with ANY frontend framework
+
+---
+
+## 🚀 Quick Start
 
-## 🚀 Zero-Config ClientInfo Collection
+### React (3 Steps)
 
-**No manual setup required!** The SDK automatically collects and injects OpenRTB-compliant client information:
+**Step 1: Install**
+```bash
+npm install @ai-ad-network/frontend-sdk
+```
 
+**Step 2: Wrap App**
 ```tsx
-import { useAdSlots } from '@ai-ad-network/frontend-sdk';
+import { AdProvider } from '@ai-ad-network/frontend-sdk';
 
-function ChatApp() {
-  const { requestAds } = useAdSlots({
-    apiBaseUrl: '/api/v1',
-    slots: [/* your slots */],
-    enabled: true,
-  });
+function App() {
+  return (
+    <AdProvider config={{ apiBaseUrl: '/api/v1', apiKey: 'ak_your_key' }}>
+      <ChatApp />
+    </AdProvider>
+  );
+}
+```
 
-  // ✅ ClientInfo is AUTOMATICALLY collected and injected!
-  await requestAds({
-    conversationContext: { query, response },
-    userContext: { sessionId },
+**Step 3: Use Ads**
+```tsx
+import { useAiAds, ActionCardAd } from '@ai-ad-network/frontend-sdk';
+
+function ChatApp() {
+  const { ads } = useAiAds(query, response, isFinished, {
+    formats: ['action_card', 'suffix'],
   });
 
-  // Request payload automatically includes:
-  // {
-  //   conversationContext: {...},
-  //   userContext: {...},
-  //   clientInfo: {    // ← Zero-config! Auto-collected!
-  //     device: { os, model, screen... },
-  //     app: { bundle, name, version... },
-  //     user: { id, consent... },
-  //     geo: { country, language... }
-  //   }
-  // }
+  return ads.map(ad => <ActionCardAd key={ad.id} ad={ad} />);
 }
 ```
 
-**What's auto-collected:**
-- 🖥️ **Device Info**: OS, model, screen size, language
-- 📱 **App Info**: Bundle ID, name, version (inferred from page)
-- 👤 **User Info**: Unique ID (auto-generated & persistent)
-- 🌍 **Geo Info**: Country, language (from timezone/locale)
+### Universal / Other Frameworks (3 Steps)
 
-📖 **See [ClientInfo Documentation](./docs/CLIENT_INFO_COLLECTION.md)**
+**Step 1: Install**
+```bash
+npm install @ai-ad-network/frontend-sdk
+```
 
----
+**Step 2: Import**
+```javascript
+import { AdManager, DOMRenderer } from '@ai-ad-network/frontend-sdk/universal';
+// or CDN: <script src="universal.iife.js"></script>
+```
+
+**Step 3: Use**
+```javascript
+const adManager = new AdManager({
+  apiBaseUrl: '/api/v1',
+  slots: [{ slotId: 'banner', position: 'top', adTypes: ['action-card'] }]
+});
+
+const result = await adManager.requestAds({
+  conversationContext: { topic: 'tech', messages: [] }
+});
+
+DOMRenderer.renderActionCard(result.slots[0].ad, container);
+```
 
-## 🆕 ClientInfo API ⭐ NEW
+---
 
-**Direct access to client information for your own use!**
+## 🆕 ClientInfo API
 
-The SDK now exposes convenient functions to access client info for analytics, personalization, A/B testing, and more.
+**Direct access to client information for analytics, personalization, A/B testing, and more!**
 
 ```typescript
 // React SDK
 import { getUserId, getDeviceInfo, getClientInfo } from '@ai-ad-network/frontend-sdk';
 
-// Universal SDK (Vue, Angular, etc.)
+// Universal SDK
 import { getUserId, getDeviceInfo, getClientInfo } from '@ai-ad-network/frontend-sdk/universal';
 
-// Get user ID for analytics
-const userId = getUserId();
-analytics.identify(userId);
-
-// Get device info for conditional features
-const device = getDeviceInfo();
-if (device.devicetype === 1) {
-  // Mobile - enable mobile optimizations
-} else {
-  // Desktop - enable desktop features
-}
-
-// Get complete info for personalization
-const info = getClientInfo();
-if (info.geo?.country === 'CN') {
-  loadChinesePaymentMethods();
-}
+// CDN
+const userId = window.AiAdNetwork.getUserId();
 ```
 
 **Available Functions:**
-- `getClientInfo()` - Get complete client information
-- `getUserId()` - Get persistent user ID
-- `getDeviceInfo()` - Get device info only
-- `getUserInfo()` - Get user info only
-- `getAppInfo()` - Get app info only
-- `getGeoInfo()` - Get geo info only
-- `getClientInfoJSON()` - Get as JSON string
-- `getClientInfoSummary()` - Get human-readable summary
+- `getClientInfo()` - Complete client information
+- `getUserId()` - Persistent user ID
+- `getDeviceInfo()` - Device info only
+- `getUserInfo()` - User info only
+- `getAppInfo()` - App info only
+- `getGeoInfo()` - Geo info only
+- `getClientInfoJSON()` - As JSON string
+- `getClientInfoSummary()` - Human-readable summary
 - `clearClientInfoCache()` - Force re-collection
 
-📖 **[Universal SDK Guide - ClientInfo API](./docs/UNIVERSAL_SDK_GUIDE.md#clientinfo-api--new)**
+**Use Cases:**
+- 📊 **Analytics**: `analytics.identify(getUserId())`
+- 🌍 **Localization**: `if (getGeoInfo()?.country === 'CN') { ... }`
+- 🧪 **A/B Testing**: `const variant = getUserId() % 2 === 0 ? 'A' : 'B'`
+- 📱 **Conditional**: `if (getDeviceInfo().devicetype === 1) { /* mobile */ }`
+
+---
+
+## 🔑 Zero-Config ClientInfo Collection
+
+**No manual setup required!** The SDK automatically collects and injects:
+
+- 🖥️ **Device Info**: OS, model, screen size, language
+- 📱 **App Info**: Bundle ID, name, version (inferred from page)
+- 👤 **User Info**: Unique persistent ID (auto-generated)
+- 🌍 **Geo Info**: Country, language (from timezone/locale)
+
+```typescript
+// ClientInfo is AUTOMATICALLY collected and injected!
+await requestAds({
+  conversationContext: { query, response },
+  userContext: { sessionId },
+});
+
+// Request payload includes:
+// {
+//   conversationContext: {...},
+//   userContext: {...},
+//   clientInfo: {    // ← Auto-collected!
+//     device: { os, model, screen... },
+//     app: { bundle, name, version... },
+//     user: { id, consent... },
+//     geo: { country, language... }
+//   }
+// }
+```
 
-📖 **See [Quick Start Guide](./docs/QUICK_START.md) for complete integration docs.**
+---
 
-## Installation
+## 📦 Installation
 
 ```bash
 npm install @ai-ad-network/frontend-sdk
@@ -144,251 +183,172 @@ yarn add @ai-ad-network/frontend-sdk
 pnpm add @ai-ad-network/frontend-sdk
 ```
 
-## Quick Start
+**Build Outputs:**
+- React SDK: `dist/index.js`, `dist/index.esm.js`
+- Universal SDK: `dist/universal/universal.*.js` (ES, CJS, UMD, IIFE)
 
-```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',
-  });
+## 📚 Documentation
 
-  return (
-    <div>
-      {/* Your chat UI */}
-      {ads.map(ad => (
-        <ActionCardAd key={ad.id} ad={ad} />
-      ))}
-    </div>
-  );
-}
-```
+- 📖 **[Quick Start Guide](./docs/QUICK_START.md)** - Get started in 3 minutes
+- 📖 **[Universal SDK Guide](./docs/UNIVERSAL_SDK_GUIDE.md)** - Framework-agnostic SDK docs
 
-## Configuration
+**Universal SDK Guide includes:**
+- AdManager API reference
+- DOMRenderer and HTMLRenderer usage
+- Web Components examples
+- Vue/Angular/Vanilla JS integration
+- ClientInfo API reference
+- CDN usage
 
-### 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>
-```
+## 🎨 Available Ad Formats
 
-## Components
+### React Components
+- **ActionCardAd** - Product cards (horizontal/vertical/compact)
+- **SuffixAd** - Inline message enhancements (block/inline/minimal)
+- **FollowUpAd** - Follow-up questions (bubble/pill/underline)
+- **SponsoredSource** - Sponsored content sources (card/minimal)
+- **LeadGenAd** - Lead generation forms
+- **StaticAd** - Traditional banner ads
 
-### ActionCardAd
+### Universal Renderers
+- `DOMRenderer.renderActionCard()`
+- `DOMRenderer.renderSuffixAd()`
+- `DOMRenderer.renderSponsoredSource()`
+- `DOMRenderer.renderLeadGenAd()`
 
-Rich media card for product ads.
+### Web Components (Framework-Agnostic)
+- `<ad-action-card>`
+- `<ad-suffix>`
+- `<ad-sponsored-source>`
+- `<ad-lead-gen>`
 
-```tsx
-<ActionCardAd
-  ad={ad}
-  variant="horizontal" // 'horizontal' | 'vertical' | 'compact'
-  onClick={() => console.log('Clicked!')}
-/>
-```
+---
 
-### SuffixAd
+## ⚡ Performance & Optimization
 
-Text-based ad appended to AI responses.
+- ✅ **SWR Caching** - Smart request deduplication
+- ✅ **Intersection Observer** - Lazy impression tracking
+- ✅ **Event Batching** - Optimized re-renders
+- ✅ **Code Splitting** - Tree-shakeable exports
+- ✅ **TypeScript** - Full type definitions
+- ✅ **Zero Runtime Overhead** - Minimal bundle size
 
-```tsx
-<SuffixAd
-  ad={ad}
-  aiContext={aiResponse}
-  variant="block" // 'block' | 'inline' | 'minimal'
-/>
-```
+---
 
-### FollowUpAd
+## 🎨 Styling & Customization
 
-Ad disguised as a follow-up question.
+### CSS Variables
 
-```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)}
-/>
+```css
+:root {
+  /* Card styling */
+  --ai-ad-card-bg: #ffffff;
+  --ai-ad-card-border: #e5e7eb;
+  --ai-ad-card-border-radius: 12px;
+  --ai-ad-card-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+
+  /* Typography */
+  --ai-ad-title-color: #111827;
+  --ai-ad-body-color: #6b7280;
+  --ai-ad-cta-bg: #10b981;
+  --ai-ad-cta-color: #ffffff;
+
+  /* Spacing */
+  --ai-ad-padding: 16px;
+  --ai-ad-gap: 12px;
+}
 ```
 
-### SponsoredSource
+---
 
-Ad in citation/source list format.
+## 📊 Examples
 
-```tsx
-<SponsoredSource
-  ad={ad}
-  variant="card" // 'card' | 'list-item' | 'minimal'
-/>
-
-// Or mix with regular sources
-<SourceListWithAds
-  sources={[{ title: 'Wikipedia', url: '...' }]}
-  ad={ad}
-  adPosition={1}
-/>
-```
+### Examples Directory
 
-## Hooks
+- `examples/vanilla-js.html` - Complete Vanilla JS demo
+- `examples/vue-example.js` - Vue 3 integration
+- `examples/client-info-usage.ts` - ClientInfo API examples
+- `examples/client-info-demo.html` - Interactive ClientInfo demo
 
-### useAiAds
+---
 
-Main hook for fetching ads.
+## ⚠️ Troubleshooting
 
-```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',
-  }
-);
-```
+### Ads not showing?
 
-### useAdTracking
+1. ✅ Console shows SDK v1.0.7+
+2. ✅ `apiBaseUrl` is correct
+3. ✅ `apiKey` is valid
+4. ✅ Network requests succeed (DevTools → Network)
 
-Tracking hook for impressions and clicks.
+### Console shows old version?
 
-```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'),
-});
+```bash
+rm -rf node_modules package-lock.json
+npm install @ai-ad-network/frontend-sdk@latest
 ```
 
-## Styling
+### ClientInfo not in request?
 
-### CSS Variables
+- **React**: Check if using `useAdSlots` or `useAiAds`
+- **Universal**: Check if using `AdManager`
+- Console should show `[SDK] ClientInfo collection: ENABLED`
 
-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;
-}
-```
+## ✅ Integration Checklist
 
-### Utility Function
+- [ ] SDK installed (`npm install @ai-ad-network/frontend-sdk`)
+- [ ] Console shows version v1.0.7+
+- [ ] React: App wrapped with `AdProvider`
+- [ ] Universal: `AdManager` initialized
+- [ ] Console shows ClientInfo collected
+- [ ] Network requests include `clientInfo` field
+- [ ] Ads are rendering
+- [ ] Analytics events firing
 
-Use the `cn` function for conditional classes:
+**Done? 🎉 Successfully integrated!**
 
-```tsx
-import { cn } from '@ai-ad-network/frontend-sdk';
+---
 
-<div className={cn(
-  'base-class',
-  isActive && 'active-class',
-  'more-classes'
-)} />
-```
+## 🆘 Support
 
-## TypeScript Support
+- 📧 Email: support@ai-ad-network.com
+- 📖 Docs: https://docs.ai-ad-network.com
+- 🐛 Issues: https://github.com/ai-ad-network/frontend-sdk/issues
 
-Full TypeScript support with exported types:
+---
 
-```tsx
-import type {
-  KoahAd,
-  IntentResult,
-  AdFormat,
-  AdSource,
-  RoutingInfo,
-} from '@ai-ad-network/frontend-sdk';
+## 📦 Package Exports
+
+```json
+{
+  "exports": {
+    ".": {
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./universal": {
+      "import": "./dist/universal/universal.esm.js",
+      "require": "./dist/universal/universal.cjs.js",
+      "types": "./dist/universal/universal.d.ts"
+    }
+  }
+}
 ```
 
-## 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
+## 📄 License
 
-# Run demo app
-cd demo-app && npm run dev
-```
+MIT
 
-## License
+---
 
-MIT
+**SDK Version**: 1.0.7
+**Last Updated**: 2026-01-26