@action-x/ad-sdk 0.1.11 → 0.1.13

package/README.md

@@ -1,185 +1,385 @@
-# @action-x/ad-sdk
+# @action-x/ad-sdk Usage Guide
 
-An ad SDK for AI conversation experiences, with zero framework dependencies. Works with Vanilla JS, Vue, React, Angular, Svelte, and more.
+Zero-dependency ad SDK for AI conversations, supporting Vanilla JS, Vue, React, Next.js, and all frameworks.
 
 ---
 
-## Installation
+## Quick Start
+
+### Installation
 
 ```bash
 npm install @action-x/ad-sdk
-# or
-yarn add @action-x/ad-sdk
-# or
-pnpm add @action-x/ad-sdk
 ```
 
-**Import styles (required):**
+### Minimal Example
 
-```js
+```typescript
+import { AdManager } from '@action-x/ad-sdk';
 import '@action-x/ad-sdk/style.css';
+
+const manager = new AdManager({
+  apiBaseUrl: 'https://network.actionx.top/api/v1',
+  apiKey: 'ak_your_api_key',
+});
+
+// Request ads after AI conversation completes
+await manager.requestAds({
+  query: 'Recommend a Bluetooth headset',
+  response: 'AI response content...',
+});
+
+// Render ad
+manager.render(document.getElementById('ad-container'));
 ```
 
 ---
 
-## AdCard Component
+## Core Concepts
 
-Below are AdCard wrapper examples for different frameworks. The component takes `query` and `response` from the AI conversation, then automatically requests and renders an ad card after the response is complete.
+### 1. AdManager Configuration
 
-### Vue 3
+```typescript
+const manager = new AdManager({
+  apiBaseUrl: string;        // Required: API endpoint
+  apiKey: string;            // Required: API key
+  cardOption?: {             // Optional: Card configuration
+    variant?: 'horizontal' | 'vertical' | 'compact';  // Layout style
+    count?: number;          // Number of ads to request, default 1
+  };
+  enabled?: boolean;         // Enable ads, default true
+  debug?: boolean;           // Debug mode, default false
+});
+```
 
-```vue
-<!-- AdCard.vue -->
-<template>
-  <div ref="adEl" />
-</template>
+### 2. Request Ads
 
-<script setup>
-import { ref, onMounted, onUnmounted } from 'vue';
-import { AdManager } from '@action-x/ad-sdk';
-import '@action-x/ad-sdk/style.css';
+```typescript
+// Simplified call (recommended)
+await manager.requestAds({
+  query: string;             // Required: User query
+  response: string;          // Required: AI response content
+});
 
-const props = defineProps(['query', 'response']);
-const adEl = ref(null);
-let manager;
+// Full call
+await manager.requestAds({
+  conversationContext: {
+    query: string;
+    response: string;
+  },
+  userContext?: {
+    sessionId?: string;
+    userId?: string;
+  }
+});
+```
 
-onMounted(async () => {
-  manager = new AdManager({
-    apiBaseUrl: 'https://your-api.example.com/api/v1',
-    apiKey: 'ak_your_api_key',
-  });
+### 3. Render Ads
+
+```typescript
+// Simplified call (renders action_card slot by default)
+manager.render(
+  container: HTMLElement,
+  options?: {
+    adIndex?: number;            // Ad index, default 0
+    variant?: string;            // Layout variant
+    onClick?: (ad) => void;      // Click callback
+    onImpression?: (ad) => void; // Impression callback
+  }
+);
+
+// Specify slot
+manager.render(
+  slotId: string,
+  container: HTMLElement,
+  options?: { ... }
+);
+```
 
-  await manager.requestAds({ query: props.query, response: props.response });
+### 4. Event Listeners
 
-  manager.render(adEl.value);
+```typescript
+manager.on('adsUpdated', (slots) => {
+  console.log('Ad data updated');
 });
 
-onUnmounted(() => manager?.destroy());
-</script>
+manager.on('adsLoading', () => {
+  console.log('Requesting ads');
+});
+
+manager.on('adsError', (error) => {
+  console.warn('Ad request failed', error);
+});
+
+manager.on('adClicked', (adId, slotId) => {
+  console.log('Ad clicked', adId);
+});
+
+manager.on('adImpression', (adId, slotId) => {
+  console.log('Ad impression', adId);
+});
 ```
 
-### React
+---
 
-```tsx
-// components/AdCard.tsx
-import { useEffect, useRef } from 'react';
-import { AdManager } from '@action-x/ad-sdk';
-import '@action-x/ad-sdk/style.css';
+## Framework Integration Examples
 
-interface Props {
-  query: string;
-  response: string;
-}
+### Vanilla JavaScript
 
-export function AdCard({ query, response }: Props) {
-  const containerRef = useRef<HTMLDivElement>(null);
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="https://unpkg.com/@action-x/ad-sdk@latest/dist/style.css" />
+</head>
+<body>
+  <div id="ad-container"></div>
+
+  <script src="https://unpkg.com/@action-x/ad-sdk@latest/dist/index.umd.js"></script>
+  <script>
+    const { AdManager } = ActionXAdSDK;
 
-  useEffect(() => {
     const manager = new AdManager({
-      apiBaseUrl: 'https://your-api.example.com/api/v1',
+      apiBaseUrl: 'https://network.actionx.top/api/v1',
       apiKey: 'ak_your_api_key',
+      debug: false,
     });
 
-    manager
-      .requestAds({ query, response })
-      .then(() => {
-        if (containerRef.current) {
-          manager.render(containerRef.current);
-        }
-      });
+    manager.on('adsUpdated', () => {
+      manager.render(document.getElementById('ad-container'));
+    });
 
-    return () => manager.destroy();
-  }, [query, response]);
+    // Call after conversation completes
+    function onChatComplete(query, response) {
+      manager.requestAds({ query, response });
+    }
+  </script>
+</body>
+</html>
+```
 
-  return <div ref={containerRef} />;
-}
+### Vue 3
+
+**Install and import styles:**
+
+```typescript
+// main.ts
+import { createApp } from 'vue';
+import App from './App.vue';
+import '@action-x/ad-sdk/style.css';
+
+createApp(App).mount('#app');
 ```
 
-### Vanilla JavaScript
+**Create Composable:**
 
-```js
+```typescript
+// composables/useAdManager.ts
+import { ref, shallowRef, onUnmounted } from 'vue';
 import { AdManager } from '@action-x/ad-sdk';
-import '@action-x/ad-sdk/style.css';
 
-const manager = new AdManager({
-  apiBaseUrl: 'https://your-api.example.com/api/v1',
-  apiKey: 'ak_your_api_key',
-});
+export function useAdManager() {
+  const manager = shallowRef(
+    new AdManager({
+      apiBaseUrl: 'https://network.actionx.top/api/v1',
+      apiKey: 'ak_your_api_key',
+      debug: false,
+    })
+  );
 
-// Request and render ads after the AI response is complete
-await manager.requestAds({
-  query: 'Recommend a Bluetooth headset',
-  response: 'Here are several popular Bluetooth headset options...',
-});
+  const isLoading = ref(false);
+  const error = ref<Error | null>(null);
+
+  manager.value.on('adsLoading', () => {
+    isLoading.value = true;
+    error.value = null;
+  });
+
+  manager.value.on('adsUpdated', () => {
+    isLoading.value = false;
+  });
+
+  manager.value.on('adsError', (e) => {
+    isLoading.value = false;
+    error.value = e;
+  });
+
+  onUnmounted(() => manager.value.destroy());
 
-manager.render(document.getElementById('ad-card'));
+  async function requestAds(query: string, response: string) {
+    await manager.value.requestAds({ query, response });
+  }
+
+  return { manager, isLoading, error, requestAds };
+}
 ```
 
-### CDN (No Build Tool)
+**Use in component:**
 
-```html
-<link rel="stylesheet" href="https://unpkg.com/@action-x/ad-sdk/style.css" />
-<script src="https://unpkg.com/@action-x/ad-sdk/dist/index.umd.js"></script>
+```vue
+<template>
+  <div class="chat-response">
+    <div class="response-text">{{ responseText }}</div>
+    <div ref="adRef" class="ad-mount"></div>
+  </div>
+</template>
 
-<div id="ad-card"></div>
+<script setup lang="ts">
+import { ref, watch, nextTick } from 'vue';
+import { useAdManager } from '@/composables/useAdManager';
 
-<script>
-  const { AdManager } = ActionXAdSDK;
+const props = defineProps<{
+  query: string;
+  responseText: string;
+  isStreaming: boolean;
+}>();
+
+const adRef = ref<HTMLElement>();
+const { manager, requestAds } = useAdManager();
+
+watch(
+  () => props.isStreaming,
+  async (streaming) => {
+    if (!streaming && props.responseText) {
+      await requestAds(props.query, props.responseText);
+      await nextTick();
+
+      if (adRef.value) {
+        manager.value.render(adRef.value);
+      }
+    }
+  }
+);
+</script>
+```
 
-  const manager = new AdManager({
-    apiBaseUrl: 'https://your-api.example.com/api/v1',
-    apiKey: 'ak_your_api_key',
-  });
+### React / Next.js
+
+**Import styles:**
+
+```typescript
+// Next.js App Router: app/layout.tsx
+import '@action-x/ad-sdk/style.css';
+
+export default function RootLayout({ children }) {
+  return <html><body>{children}</body></html>;
+}
+
+// Vite + React: src/main.tsx
+import '@action-x/ad-sdk/style.css';
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(<App />);
+```
+
+**Create Hook:**
+
+```typescript
+// hooks/useAdManager.ts
+import { useEffect, useRef, useState, useCallback } from 'react';
+import { AdManager } from '@action-x/ad-sdk';
+
+export function useAdManager() {
+  const managerRef = useRef<AdManager | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [isReady, setIsReady] = useState(false);
 
-  manager
-    .requestAds({ query: 'User question', response: 'AI response' })
-    .then(() => {
-      manager.render(document.getElementById('ad-card'));
+  useEffect(() => {
+    const manager = new AdManager({
+      apiBaseUrl: 'https://network.actionx.top/api/v1',
+      apiKey: 'ak_your_api_key',
+      debug: false,
     });
-</script>
+
+    manager.on('adsLoading', () => setIsLoading(true));
+    manager.on('adsUpdated', () => {
+      setIsLoading(false);
+      setIsReady(true);
+    });
+    manager.on('adsError', (e) => {
+      setIsLoading(false);
+      setError(e);
+    });
+
+    managerRef.current = manager;
+    return () => manager.destroy();
+  }, []);
+
+  const requestAds = useCallback(async (query: string, response: string) => {
+    if (!managerRef.current) return;
+    await managerRef.current.requestAds({ query, response });
+  }, []);
+
+  return { manager: managerRef.current, isLoading, isReady, error, requestAds };
+}
 ```
 
----
+**Create Ad Component:**
 
-## Usage Example
+```tsx
+// components/AdCard.tsx
+'use client';
 
-### Render an Ad Card After AI Response Completes
+import { useEffect, useRef } from 'react';
+import type { AdManager } from '@action-x/ad-sdk';
 
-Using React as an example, render AdCard after streaming output finishes:
+interface AdCardProps {
+  manager: AdManager | null;
+  isReady: boolean;
+  className?: string;
+}
+
+export function AdCard({ manager, isReady, className }: AdCardProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!isReady || !manager || !containerRef.current) return;
+    manager.render(containerRef.current);
+  }, [isReady, manager]);
+
+  return <div ref={containerRef} className={className} />;
+}
+```
+
+**Use in page:**
 
 ```tsx
+// app/chat/page.tsx
+'use client';
+
 import { useState } from 'react';
-import { AdCard } from './components/AdCard';
+import { useAdManager } from '@/hooks/useAdManager';
+import { AdCard } from '@/components/AdCard';
 
-export function ChatMessage() {
+export default function ChatPage() {
   const [query, setQuery] = useState('');
   const [response, setResponse] = useState('');
   const [isStreaming, setIsStreaming] = useState(false);
 
-  async function handleSend(userQuery: string) {
-    setQuery(userQuery);
-    setIsStreaming(true);
-    setResponse('');
-
-    // Receive AI response as a stream
-    const stream = await fetchAIResponse(userQuery);
-    let fullResponse = '';
-    for await (const chunk of stream) {
-      fullResponse += chunk;
-      setResponse(fullResponse);
-    }
+  const { manager, isReady, requestAds } = useAdManager();
 
+  const handleSend = async () => {
+    setIsStreaming(true);
+    const aiResponse = await fetchAIResponse(query);
+    setResponse(aiResponse);
     setIsStreaming(false);
-    // After response completes, AdCard will request and render automatically
-  }
+
+    await requestAds(query, aiResponse);
+  };
 
   return (
     <div>
-      <div className="response">{response}</div>
-
-      {/* Show ad card after response streaming ends */}
-      {!isStreaming && response && (
-        <AdCard query={query} response={response} />
+      <input value={query} onChange={(e) => setQuery(e.target.value)} />
+      <button onClick={handleSend}>Send</button>
+
+      {response && (
+        <div>
+          <p>{response}</p>
+          <AdCard manager={manager} isReady={isReady} className="mt-4" />
+        </div>
       )}
     </div>
   );
@@ -188,63 +388,146 @@ export function ChatMessage() {
 
 ---
 
-## Configuration
+## Custom Styles
+
+The SDK uses the `ax-ad-*` namespace. Override styles via CSS:
+
+```css
+/* Custom CTA button */
+.ax-ad-cta {
+  background-color: #7c3aed !important;
+  border-radius: 20px;
+}
+
+.ax-ad-cta:hover {
+  background-color: #6d28d9 !important;
+}
+
+/* Custom card style */
+.ax-ad-card {
+  border: none;
+  border-radius: 12px;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
+}
 
-### `new AdManager(config)`
+/* Dark mode */
+@media (prefers-color-scheme: dark) {
+  .ax-ad-card {
+    background: #1f2937;
+    border-color: #374151;
+    color: #f9fafb;
+  }
+  .ax-ad-title { color: #f9fafb; }
+  .ax-ad-body { color: #9ca3af; }
+}
 
-| Parameter | Type | Required | Description |
-|------|------|------|------|
-| `apiBaseUrl` | `string` | Yes | API base URL, e.g. `https://your-api.example.com/api/v1` |
-| `apiKey` | `string` | Yes | API authentication key |
-| `cardOption` | `CardOption` | No | Card options with sensible defaults |
+/* Hide on mobile */
+@media (max-width: 640px) {
+  .ax-ad-card { display: none; }
+}
+```
 
-### Card Options `cardOption`
+---
 
-| Parameter | Type | Default | Description |
-|------|------|--------|------|
-| `variant` | `'horizontal' \| 'vertical' \| 'compact'` | `'horizontal'` | Layout style |
-| `count` | `number` | `1` | Number of ads to request |
+## Debugging Tips
 
-**Customization example:**
+### Enable Debug Logging
 
-```js
-new AdManager({
+```typescript
+const manager = new AdManager({
   apiBaseUrl: '...',
   apiKey: '...',
-  cardOption: {
-    variant: 'vertical',
-    count: 2,
-  },
+  debug: true,  // Outputs detailed logs to console
 });
 ```
 
-### `requestAds(context)`
+### Check Ad Response
 
-| Parameter | Type | Required | Description |
-|------|------|------|------|
-| `query` | `string` | Yes | User question |
-| `response` | `string` | Yes | AI response text |
+```typescript
+manager.on('adsUpdated', (slots) => {
+  console.log('Ad slots:', Object.keys(slots));
 
-### `render(container, options?)`
+  Object.entries(slots).forEach(([slotId, slot]) => {
+    console.log(`[${slotId}] Status:`, slot.status);
+    console.log(`[${slotId}] Ad count:`, slot.ads.length);
 
-| Parameter | Type | Description |
-|------|------|------|
-| `container` | `HTMLElement` | Mount container |
-| `options.onClick` | `(ad) => void` | Click callback |
-| `options.onImpression` | `(ad) => void` | Impression callback |
+    if (slot.status === 'no_fill') {
+      console.log('  → No fill (insufficient inventory or targeting mismatch)');
+    }
+    if (slot.status === 'error') {
+      console.error('  → Slot error:', slot.error);
+    }
+  });
+});
+```
+
+### Common Issues
+
+| Issue | Possible Cause | Solution |
+|-------|---------------|----------|
+| Empty ad container | `render()` called before `requestAds()` completes | Call `render()` inside `adsUpdated` event |
+| Styles not applied | Forgot to import CSS | Ensure `import '@action-x/ad-sdk/style.css'` |
+| Console 403 error | Invalid or missing apiKey | Check apiKey configuration |
+| TypeScript type errors | Type definitions not generated | Run `npm run build` |
+| Ad status 'no_fill' | No matching ads | Expected behavior, check `manager.hasAds()` before rendering |
+| Clicks unresponsive | Container obscured | Check CSS z-index and pointer-events |
 
 ---
 
-## Event Listeners
+## API Reference
+
+### AdManager
+
+#### Constructor
 
-```js
-manager.on('adsUpdated',   (slots) => { /* ad data ready */ });
-manager.on('adsLoading',   ()      => { /* requesting */ });
-manager.on('adsError',     (err)   => { /* request failed */ });
-manager.on('adClicked',    (adId, slotId) => { });
-manager.on('adImpression', (adId, slotId) => { });
+```typescript
+new AdManager(config: AdManagerConfig)
 ```
 
+#### Methods
+
+```typescript
+// Request ads
+requestAds(context: { query: string; response: string }): Promise<AdResponseBatch>
+requestAds(context: { conversationContext, userContext? }): Promise<AdResponseBatch>
+
+// Render ads
+render(container: HTMLElement, options?: RenderOptions): HTMLElement | null
+render(slotId: string, container: HTMLElement, options?: RenderOptions): HTMLElement | null
+
+// Check if ads available
+hasAds(slotId: string): boolean
+
+// Get ad data
+getAds(slotId: string): any[]
+getSlots(slotId?: string): Record<string, AdSlotResponse> | AdSlotResponse | undefined
+
+// Destroy instance
+destroy(): void
+
+// Event listeners
+on(event: string, handler: Function): void
+off(event: string, handler: Function): void
+```
+
+#### Events
+
+- `adsLoading` - Started requesting ads
+- `adsUpdated` - Ad data updated
+- `adsError` - Request failed
+- `adClicked` - Ad clicked
+- `adImpression` - Ad impression
+
 ---
 
-**Version**: `0.1.0` | **License**: MIT
+## Version Info
+
+- Current version: `0.1.12`
+- License: MIT
+- Repository: [GitHub](https://github.com/action-x/ad-sdk)
+
+---
+
+## Support
+
+For questions, contact ActionX support or submit an Issue.