@the_ro_show/agent-ads-sdk 0.4.3 → 0.6.0

package/README.md

@@ -4,22 +4,21 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 
-**The first ad network built for AI agents.** Monetize your AI agent with contextual, high-intent sponsored suggestions. Open source, transparent, developer-first.
+Ad network for AI agents. Pass user messages, get contextually relevant ads, earn revenue. Similar to AdSense but designed for conversational interfaces. It's time to start monetizing your AI agents!
 
-- 🚀 **5-minute integration** - npm install + 5 lines of code
-- 💰 **70% revenue share** - You keep the majority, we only win when you do
-- 🎯 **10-15% CTR** - High-intent placements, not banner ads
-- 🔓 **100% Open Source** - Audit every line, full transparency
+- **70% revenue share** - You keep most of the earnings (I use the remaining 30% to onboard advertisers and support that ecosystem).
+- **Simple integration** - One API call to get ads
 
-## Quick Start
+---
 
-### 1. Get Your API Key
+## Quick Start
 
-**Sign up at [attentionmarket.com/signup](https://attentionmarket.com/signup)** (30 seconds, free forever)
+### 1. Get API Key
 
-You'll receive:
-- Test key: `am_test_...` (for development)
-- Live key: `am_live_...` (for production)
+Sign up at [attentionmarket.com/signup](https://api.attentionmarket.ai/) to receive:
+- Test key: `am_test_...`
+- Live key: `am_live_...`
+- Agent ID
 
 ### 2. Install
 
@@ -27,295 +26,347 @@ You'll receive:
 npm install @the_ro_show/agent-ads-sdk
 ```
 
-### 3. Integrate (5 lines of code)
+### 3. Basic Usage
 
 ```typescript
-import { AttentionMarketClient, detectIntent, buildTaxonomy } from '@the_ro_show/agent-ads-sdk';
+import { AttentionMarketClient } from '@the_ro_show/agent-ads-sdk';
 
 const client = new AttentionMarketClient({
-  apiKey: process.env.ATTENTIONMARKET_API_KEY  // Your test or live key
+  apiKey: process.env.ATTENTIONMARKET_API_KEY,
+  agentId: 'your_agent_id'
 });
 
-// When your agent helps users, show relevant ads
-const userQuery = "I need car insurance for my Honda";
-const intent = detectIntent(userQuery);  // → "quote" or "compare" or "research"
-const taxonomy = buildTaxonomy('insurance', 'auto', 'full_coverage', intent);
-
-const decision = await client.decide({
-  request_id: crypto.randomUUID(),
-  agent_id: 'your_agent_id',
-  placement: { type: 'sponsored_suggestion' },
-  opportunity: {
-    intent: { taxonomy },  // "insurance.auto.full_coverage.quote"
-    context: { country: 'US', language: 'en', platform: 'web' }
-  }
+// Request an ad based on user message
+const ad = await client.decideFromContext({
+  userMessage: "I need car insurance"
 });
 
-if (decision.status === 'filled') {
-  const ad = decision.units[0];
-  console.log(`[Sponsored] ${ad.suggestion.title}`);
-  // User clicks → You earn $5-50
+if (ad) {
+  console.log(ad.creative.title);
+  console.log(ad.creative.body);
+  console.log(ad.creative.cta);
 }
 ```
 
-**That's it!** Start earning from relevant ads.
-
 ---
 
-## 🆕 What's New in v0.4.0
+## How It Works
+
+1. User interacts with your agent: `"I need help with estate planning"`
+2. You pass the message to `decideFromContext()`
+3. We return a matching ad from our network
+4. You display it and track clicks to earn revenue
 
-### Hierarchical Taxonomy Matching
+The API handles intent detection and ad matching automatically.
 
-Target broadly, match specifically:
+---
+
+## Complete Example
+
+Full integration including ad retrieval, display, and click tracking:
 
 ```typescript
-// Advertiser targets: "insurance.auto"
-// Your agent requests: "insurance.auto.full_coverage.quote"
-// ✅ Matches! (0.7 relevance score)
+import { AttentionMarketClient } from '@the_ro_show/agent-ads-sdk';
 
-// Your agent requests: "insurance.auto.liability.compare"
-// ✅ Also matches! (0.7 relevance score)
+const client = new AttentionMarketClient({
+  apiKey: process.env.ATTENTIONMARKET_API_KEY,
+  agentId: 'your_agent_id'
+});
 
-// Your agent requests: "insurance.home.flood.quote"
-// ❌ No match (different category)
-```
+async function handleUserMessage(userMessage: string) {
+  const ad = await client.decideFromContext({ userMessage });
 
-**Result:** 3x more ad inventory, higher fill rates.
+  if (!ad) {
+    return null;  // No ads available
+  }
 
-### New Helper Functions
+  // Display ad (you can customize this)
+  const displayMessage = `\n[Sponsored] ${ad.disclosure.sponsor_name}\n${ad.creative.title}\n${ad.creative.body}\n${ad.creative.cta}\n`;
+  console.log(displayMessage);
 
-**Auto-detect user intent:**
-```typescript
-import { detectIntent } from '@the_ro_show/agent-ads-sdk';
+  // Track click when user clicks
+  await client.trackClick({
+    agent_id: 'your_agent_id',
+    request_id: ad.request_id,
+    decision_id: ad.offer_id,
+    unit_id: ad.offer_id,
+    tracking_token: ad.tracking_token,
+    href: ad.click_url,
+    click_context: displayMessage  // What was actually shown to user
+  });
 
-detectIntent("What is car insurance?")           // → 'research'
-detectIntent("Compare car insurance options")    // → 'compare'
-detectIntent("Get car insurance quote")          // → 'quote'
-detectIntent("I want to buy car insurance")      // → 'apply'
+  return ad;
+}
 ```
 
-**Build taxonomies easily:**
-```typescript
-import { buildTaxonomy } from '@the_ro_show/agent-ads-sdk';
+---
 
-const taxonomy = buildTaxonomy('insurance', 'auto', 'full_coverage', 'quote');
-// → "insurance.auto.full_coverage.quote"
-```
+## API Reference
 
-**Get taxonomy suggestions:**
-```typescript
-import { suggestTaxonomies } from '@the_ro_show/agent-ads-sdk';
+### Primary API
 
-const suggestions = suggestTaxonomies("I need a lawyer for divorce");
-// → ['legal.family.divorce.consultation', 'legal.family.custody.consultation']
-```
+#### `decideFromContext(params)` → `Promise <OfferResponse | null>`
+
+Pass a user message and optionally conversation history. Returns a matching ad or null if no fill.
 
-**Validate taxonomies:**
 ```typescript
-import { isValidTaxonomy, parseTaxonomy } from '@the_ro_show/agent-ads-sdk';
+const ad = await client.decideFromContext({
+  userMessage: "I need help with estate planning",
+  conversationHistory: ["My father passed away recently"],  // Optional
+  context: { geo: { city: 'NYC', country: 'US' } }          // Optional
+});
+```
 
-isValidTaxonomy('insurance.auto.full_coverage.quote')  // → true
-isValidTaxonomy('invalid.format')                      // → false
+Returns ad with:
+- `creative.title` - Ad headline
+- `creative.body` - Ad description
+- `creative.cta` - Call to action
+- `click_url` - URL to open on click
+- `tracking_token` - Required for revenue tracking
+- `disclosure` - Sponsor information
 
-const parsed = parseTaxonomy('insurance.auto.full_coverage.quote');
-// → { vertical: 'insurance', category: 'auto', subcategory: 'full_coverage', intent: 'quote' }
-```
+### Revenue Tracking
 
----
+#### `trackClick(params)` → `Promise<void>`
 
-## Common Taxonomies
+Records user clicks for revenue attribution. Call this when a user clicks an ad. Handles deduplication and retries automatically.
 
-### Insurance ($20-54 CPC)
-```typescript
-'insurance.auto.full_coverage.quote'
-'insurance.auto.liability.compare'
-'insurance.home.standard.quote'
-'insurance.life.term.compare'
-'insurance.health.individual.quote'
-```
+**Required:** `click_context` - The actual message shown to the user. This helps optimize ad creative based on what converts.
 
-### Legal ($50-150 CPC)
 ```typescript
-'legal.personal_injury.accident.consultation'
-'legal.family.divorce.consultation'
-'legal.criminal.defense.consultation'
-'legal.immigration.visa.consultation'
-'legal.estate_planning.will.consultation'
+await client.trackClick({
+  agent_id: 'your_agent_id',
+  request_id: ad.request_id,
+  decision_id: ad.offer_id,
+  unit_id: ad.offer_id,
+  tracking_token: ad.tracking_token,
+  href: ad.click_url,
+  click_context: "The message shown to user that they clicked"
+});
 ```
 
-### Financial Services ($15-50 CPC)
-```typescript
-'financial.loans.personal.quote'
-'financial.loans.mortgage.compare'
-'financial.credit_cards.rewards.compare'
-'financial.investing.brokerage.trial'
-```
+### Testing
+
+#### `MockAttentionMarketClient`
+
+Mock client for testing without API calls. Simulates latency and fill rate behavior.
 
-### B2B SaaS ($10-100 CPC)
 ```typescript
-'business.saas.crm.trial'
-'business.saas.project_management.trial'
-'business.ecommerce.platform.trial'
-'business.saas.marketing_automation.trial'
+import { MockAttentionMarketClient } from '@the_ro_show/agent-ads-sdk';
+
+const client = new MockAttentionMarketClient({
+  fillRate: 1.0,     // Always return ads (0.0 = never, 0.5 = 50% of time)
+  latencyMs: 100,    // Simulate API latency
+  verbose: true      // Log what's happening
+});
+
+// Works exactly like the real client
+const ad = await client.decideFromContext({ userMessage: "test" });
 ```
 
-### Home Services ($5-30 CPC)
+---
+
+## Advanced Features
+
+<details>
+<summary><strong>Click to view advanced APIs (most developers don't need these)</strong></summary>
+
+<br>
+
+The simple `decideFromContext()` API handles everything for 90% of use cases. But if you need more control:
+
+### Manual Category Targeting
+
+#### `decide()` - Specify exact categories
+When you know the exact category, use manual taxonomy matching for deterministic results.
+
 ```typescript
-'home_services.moving.local.quote'
-'home_services.cleaning.regular.book'
-'home_services.plumbing.emergency.quote'
-'home_services.remodeling.kitchen.quote'
+const decision = await client.decide({
+  request_id: crypto.randomUUID(),
+  agent_id: 'your_agent_id',
+  placement: { type: 'sponsored_suggestion' },
+  opportunity: {
+    intent: { taxonomy: 'insurance.auto.full_coverage.quote' },
+    context: { country: 'US', language: 'en', platform: 'web' }
+  }
+});
 ```
 
-**See all 50+ taxonomies:** [TAXONOMY_SYSTEM.md](./TAXONOMY_SYSTEM.md)
+See [TAXONOMY_SYSTEM.md](./TAXONOMY_SYSTEM.md) for all categories.
 
 ---
 
-## Complete Example
+### 🌐 Intenture Network APIs (Agent-to-Agent)
+
+#### `requestOffer()` - Intent-key based matching for high confidence scenarios
+When you KNOW what the user wants (they said "order coffee" or "book lawyer"), use intent-keys like `coffee.purchase.delivery` for deterministic matching. Enables agent-to-agent coordination and revenue sharing.
 
 ```typescript
-import {
-  AttentionMarketClient,
-  buildTaxonomy,
-  detectIntent
-} from '@the_ro_show/agent-ads-sdk';
+const offer = await client.requestOffer({
+  placementId: 'order_card',
+  intentKey: 'coffee.purchase.delivery',
+  context: { geo: { city: 'SF', country: 'US' } }
+});
+```
 
-const client = new AttentionMarketClient({
-  apiKey: process.env.ATTENTIONMARKET_API_KEY
+#### `requestOfferFromContext()` - Semantic discovery for fuzzy intents
+When you're NOT sure what they need (they said "I'm so tired"), pass the conversation and let semantic search find relevant offers. Auto-limits history to last 5 messages.
+
+```typescript
+const offer = await client.requestOfferFromContext({
+  placementId: 'chat_suggestion',
+  userMessage: "I'm so tired, long day at work...",
+  conversationHistory: ["How was your day?", "Exhausting"],
+  context: { geo: { city: 'NYC' } }
 });
+```
 
-async function showRelevantAd(userQuery: string) {
-  // 1. Detect what the user wants
-  const intent = detectIntent(userQuery);
-
-  // 2. Build taxonomy (or use your own logic)
-  let taxonomy: string;
-  if (/insurance|car|auto/i.test(userQuery)) {
-    taxonomy = buildTaxonomy('insurance', 'auto', 'full_coverage', intent);
-  } else if (/lawyer|legal|divorce/i.test(userQuery)) {
-    taxonomy = buildTaxonomy('legal', 'family', 'divorce', 'consultation');
-  } else {
-    return null; // No relevant ads
-  }
+#### Revenue Share (Preview) - Track referrals between agents
+If another agent sends users to you, include their agent_id to split revenue (0-50%). Currently in preview mode (logs only) - payouts activate Q2 2026. Think affiliate marketing for AI agents.
 
-  // 3. Request ads
-  const decision = await client.decide({
-    request_id: crypto.randomUUID(),
-    agent_id: 'your_agent_id',
-    placement: { type: 'sponsored_suggestion' },
-    opportunity: {
-      intent: { taxonomy },
-      context: {
-        country: 'US',
-        language: 'en',
-        platform: 'web'
-      }
-    }
-  });
+```typescript
+const offer = await client.requestOffer({
+  intentKey: 'legal.divorce.consultation',
+  sourceAgentId: 'agt_referrer_123',  // Agent who sent the user
+  revenueSharePct: 30,                 // Give them 30% of revenue
+  // ... other params
+});
+```
 
-  // 4. Show ad if available
-  if (decision.status === 'filled') {
-    const ad = decision.units[0];
+---
 
-    console.log(`\n[${ad.disclosure.label}] ${ad.disclosure.sponsor_name}`);
-    console.log(ad.suggestion.title);
-    console.log(ad.suggestion.body);
-    console.log(`→ ${ad.suggestion.cta}\n`);
+### 🧠 Intent Detection
 
-    // 5. Track impression (for billing)
-    await client.trackImpression({
-      agent_id: 'your_agent_id',
-      request_id: decision.request_id,
-      decision_id: decision.decision_id,
-      unit_id: ad.unit_id,
-      tracking_token: ad.tracking.token
-    });
+#### `detectIntent()` - Auto-detect where users are in their journey
+Analyzes queries to determine if they're researching ("what is X?"), comparing ("X vs Y"), getting quotes ("how much?"), or ready to buy ("I want X"). Returns 'research', 'compare', 'quote', 'apply', 'support', or 'other'.
 
-    // 6. Track click when user clicks (you earn money!)
-    // await client.trackClick({ ... });
+```typescript
+detectIntent("What is car insurance?")        // → 'research'
+detectIntent("Compare car insurance options") // → 'compare'
+detectIntent("Get car insurance quote")       // → 'quote'
+detectIntent("I want to buy car insurance")   // → 'apply'
+```
 
-    return ad;
-  }
+#### `buildTaxonomy()` - Type-safe taxonomy builder
+Constructs valid taxonomies like "insurance.auto.full_coverage.quote" with validation. Pass vertical, category, subcategory, and intent - it handles the formatting and catches errors.
 
-  return null; // No ads available
-}
+```typescript
+const taxonomy = buildTaxonomy('insurance', 'auto', 'full_coverage', 'quote');
+// → "insurance.auto.full_coverage.quote"
+```
+
+#### `suggestTaxonomies()` - Smart taxonomy recommendations
+Pass a user query and get back 3-5 relevant taxonomy suggestions ranked by relevance. Great for when you're not sure which category to use.
 
-// Example usage
-await showRelevantAd("I need car insurance for my Honda");
-await showRelevantAd("I need a divorce lawyer in California");
+```typescript
+const suggestions = suggestTaxonomies("I need a lawyer for divorce");
+// → ['legal.family.divorce.consultation', 'legal.family.custody.consultation']
 ```
 
+#### Taxonomy Utilities
+- `isValidTaxonomy(taxonomy)` - Validate taxonomy format
+- `parseTaxonomy(taxonomy)` - Parse taxonomy into components
+- `getBaseTaxonomy(taxonomy)` - Get taxonomy without intent
+- `matchesTaxonomy(tax1, tax2)` - Check if taxonomies match
+- `getVertical(taxonomy)` - Extract industry vertical
+
 ---
 
-## API Reference
+### 🎨 Response Formatting
 
-### Client Methods
+#### `formatNatural()` - Convert ads into natural conversation
+Transforms sponsored suggestions into conversational responses that feel native to your agent. Handles disclosure labels, CTA integration, and tone matching automatically.
 
-**`client.decide(request)`** - Get ads (convenience method)
 ```typescript
-const decision = await client.decide({
-  request_id: crypto.randomUUID(),
-  agent_id: 'your_agent_id',
-  placement: { type: 'sponsored_suggestion' },
-  opportunity: {
-    intent: { taxonomy: 'insurance.auto.full_coverage.quote' },
-    context: { country: 'US', language: 'en', platform: 'web' }
-  }
+const formatted = formatNatural(ad, {
+  tone: 'friendly',
+  includeDisclosure: true
 });
+// → "I found a great option for you! [Sponsored: Lemonade]..."
 ```
 
-**`client.decideRaw(request)`** - Get full response with metadata
+#### `formatInlineMention()` - Subtle in-message placement
+Weaves ads into your agent's response as natural mentions. Like "Btw, Lemonade offers great rates for new drivers [Sponsored]". Less intrusive than separate ad blocks.
+
 ```typescript
-const response = await client.decideRaw(request);
-// Returns: { status, request_id, decision_id, units[], ttl_ms }
+const mention = formatInlineMention(ad);
+// → "Btw, Lemonade offers 20% off for new drivers [Sponsored]"
 ```
 
-**`client.trackImpression(params)`** - Track when ad is shown
+#### `validateAdFits()` - Check if ad matches conversation context
+Before showing an ad, validate it fits the current conversation. Checks relevance, tone, and user intent to avoid jarring placements.
+
+```typescript
+const fits = validateAdFits(ad, conversationContext);
+if (fits) {
+  // Show the ad
+}
+```
+
+---
+
+### 📊 Event Tracking
+
+#### `trackImpression()` - Log when users see an ad
+Record that an ad was shown to a user. Required for billing and analytics. Include the unit_id and tracking token from the ad response.
+
 ```typescript
 await client.trackImpression({
   agent_id: 'your_agent_id',
-  request_id: 'req_123',
-  decision_id: 'dec_456',
-  unit_id: 'unit_789',
-  tracking_token: 'trk_abc'
+  request_id: decision.request_id,
+  decision_id: decision.decision_id,
+  unit_id: ad.unit_id,
+  tracking_token: ad.tracking.token
 });
 ```
 
-**`client.trackClick(params)`** - Track when ad is clicked (you earn $)
+#### `trackClick()` - Log when users click an ad
+Record when users interact with ads. This is how you get paid. Automatically deduplicates to prevent double-charging.
+
+**Required:** `click_context` - The actual message shown to the user that they clicked.
+
 ```typescript
 await client.trackClick({
   agent_id: 'your_agent_id',
-  request_id: 'req_123',
-  decision_id: 'dec_456',
-  unit_id: 'unit_789',
-  tracking_token: 'trk_abc',
-  href: 'https://advertiser.com'
+  request_id: decision.request_id,
+  decision_id: decision.decision_id,
+  unit_id: ad.unit_id,
+  tracking_token: ad.tracking.token,
+  href: ad.suggestion.action_url,
+  click_context: 'The message shown to user when they clicked'
 });
 ```
 
-### Helper Functions
+---
 
-- `buildTaxonomy(vertical, category, subcategory, intent?)` - Build taxonomy string
-- `detectIntent(query)` - Auto-detect user intent from query
-- `suggestTaxonomies(query)` - Get relevant taxonomy suggestions
-- `isValidTaxonomy(taxonomy)` - Validate taxonomy format
-- `parseTaxonomy(taxonomy)` - Parse taxonomy into components
-- `getBaseTaxonomy(taxonomy)` - Get taxonomy without intent
-- `matchesTaxonomy(tax1, tax2)` - Check if taxonomies match
-- `getVertical(taxonomy)` - Extract industry vertical
+### 🛠️ Helper Utilities
 
-### Security Helpers
+#### `createOpportunity()` - Build opportunity objects easily
+Helper to construct the opportunity payload for decide() calls. Handles defaults and validation.
 
-- `escapeHTML(text)` - Escape HTML to prevent XSS
-- `sanitizeURL(url)` - Validate and sanitize URLs
+```typescript
+const opportunity = createOpportunity({
+  taxonomy: 'insurance.auto.quote',
+  country: 'US'
+});
+```
 
-**Always sanitize ad content before rendering!**
+#### Security Helpers
+- `escapeHTML(text)` - Sanitize ad content before rendering to prevent XSS attacks
+- `sanitizeURL(url)` - Validate and sanitize URLs before opening
+
+**Always sanitize ad content before displaying in web contexts!**
+
+#### ID Generation
+- `generateUUID()` - Create unique request IDs (crypto-secure randomness)
+- `generateTimestamp()` - Generate timestamps that match our API requirements
 
 ---
 
-## Testing
+### 🧪 Testing
 
-### Mock Client (No API calls)
+#### `MockAttentionMarketClient` - Test without real API calls
+Drop-in replacement that returns fake ads for testing. Simulates latency, errors, and no-fill scenarios. Perfect for unit tests and local development.
 
 ```typescript
 import { MockAttentionMarketClient } from '@the_ro_show/agent-ads-sdk';
@@ -330,42 +381,96 @@ const client = new MockAttentionMarketClient({
 const decision = await client.decide(request);
 ```
 
-### Test Taxonomies
+---
+
+### ⚠️ Error Handling
+
+#### `APIRequestError` - API returned an error response
+Thrown when the backend rejects your request (invalid key, bad params, etc). Includes detailed error message and request_id for debugging.
+
+#### `NetworkError` - Connection failed
+Network issues, DNS failures, or backend unavailable. Includes automatic retry logic for transient failures.
+
+#### `TimeoutError` - Request exceeded timeout
+Request took too long (default 5s). Configure with `timeoutMs` in constructor.
 
-Use your test key with real API:
 ```typescript
-const client = new AttentionMarketClient({
-  apiKey: process.env.ATTENTIONMARKET_TEST_KEY  // am_test_...
-});
+try {
+  const decision = await client.decide(request);
+} catch (error) {
+  if (error instanceof TimeoutError) {
+    console.log('Request timed out, try again');
+  } else if (error instanceof NetworkError) {
+    console.log('Network issue, retrying...');
+  } else if (error instanceof APIRequestError) {
+    console.log('API error:', error.message);
+  }
+}
 ```
 
+</details>
+
 ---
 
-## Security
+## Using Test vs Live Keys
 
-### ⚠️ CRITICAL: Server-Side Only
+### Test Environment
+Use your test key for development:
+```typescript
+const client = new AttentionMarketClient({
+  apiKey: process.env.ATTENTIONMARKET_TEST_KEY  // am_test_...
+});
+```
 
-**Never use this SDK in browsers or mobile apps.** Your API key has full access to your account.
+### Production Environment
+Use your live key for production:
+```typescript
+const client = new AttentionMarketClient({
+  apiKey: process.env.ATTENTIONMARKET_API_KEY  // am_live_...
+});
+```
 
-✅ **Safe:** Node.js, serverless functions, server-side rendering
-❌ **Unsafe:** Browser JavaScript, React/Vue components, mobile apps
+---
 
-### Sanitize Ad Content
+## Sanitizing Ad Content
 
-Always escape ad content before rendering:
+Ad creative comes from third-party advertisers. Always sanitize before rendering in HTML contexts:
 
 ```typescript
 import { escapeHTML, sanitizeURL } from '@the_ro_show/agent-ads-sdk';
 
-const safeTitle = escapeHTML(ad.suggestion.title);
-const safeURL = sanitizeURL(ad.suggestion.action_url);
+const safeTitle = escapeHTML(ad.creative.title);
+const safeURL = sanitizeURL(ad.click_url);
 
 if (safeURL) {
   element.innerHTML = `<a href="${safeURL}">${safeTitle}</a>`;
 }
 ```
 
-**See [SECURITY.md](./SECURITY.md) for complete guidelines.**
+<details>
+<summary><strong>Security considerations</strong></summary>
+
+<br>
+
+### Server-Side Only
+
+This SDK must run server-side. Do not use in browsers or mobile apps where the API key would be exposed.
+
+**Supported:**
+- Node.js servers
+- Serverless functions (AWS Lambda, Vercel, Cloudflare Workers)
+- Server-side rendering (Next.js, Remix)
+
+**Not supported:**
+- Browser JavaScript
+- Client-side React/Vue/Angular
+- Mobile apps
+
+### Additional Guidelines
+
+See [SECURITY.md](./SECURITY.md) for complete security best practices.
+
+</details>
 
 ---
 
@@ -432,6 +537,61 @@ npx tsx examples/claude-tool-use-minimal.ts
 
 ---
 
+## Available Ad Categories
+
+The network currently has active campaigns in these verticals:
+
+| Category | CPC Range | Common Intents |
+|----------|-----------|----------------|
+| Legal | $50-150 | Divorce, estate planning, personal injury, immigration |
+| Insurance | $20-54 | Auto, home, life, health |
+| Financial | $15-50 | Loans, credit cards, mortgages, investing |
+| B2B SaaS | $10-100 | CRM, project management, ecommerce tools |
+| Home Services | $5-30 | Moving, cleaning, repairs |
+| Travel | $3-20 | Flights, hotels, packages |
+| Ecommerce | $2-15 | Retail, subscriptions |
+| Education | $10-50 | Courses, certifications |
+
+The semantic matching API automatically maps user queries to available inventory. If your use case isn't listed, contact support@attentionmarket.com to discuss adding new categories.
+
+<details>
+<summary><strong>View detailed taxonomy reference (advanced users only)</strong></summary>
+
+<br>
+
+**Full taxonomy list:** [TAXONOMY_SYSTEM.md](./TAXONOMY_SYSTEM.md)
+
+Example taxonomies for advanced `decide()` API:
+```typescript
+// Insurance
+'insurance.auto.full_coverage.quote'
+'insurance.auto.liability.compare'
+'insurance.home.standard.quote'
+'insurance.life.term.compare'
+
+// Legal
+'legal.personal_injury.accident.consultation'
+'legal.family.divorce.consultation'
+'legal.estate_planning.will.consultation'
+
+// Financial
+'financial.loans.personal.quote'
+'financial.credit_cards.rewards.compare'
+'financial.investing.brokerage.trial'
+
+// B2B SaaS
+'business.saas.crm.trial'
+'business.saas.project_management.trial'
+
+// Home Services
+'home_services.moving.local.quote'
+'home_services.plumbing.emergency.quote'
+```
+
+</details>
+
+---
+
 ## Support
 
 - **Issues:** [GitHub Issues](https://github.com/rtrivedi/agent-ads-sdk/issues)
@@ -448,27 +608,4 @@ MIT
 
 ## Changelog
 
-### v0.4.0 (2026-02-03)
-
-**New Features:**
-- ✨ Hierarchical taxonomy matching (3x more inventory)
-- ✨ `buildTaxonomy()` helper function
-- ✨ `detectIntent()` auto-intent detection
-- ✨ `suggestTaxonomies()` get relevant taxonomies
-- ✨ `isValidTaxonomy()` and `parseTaxonomy()` validators
-- ✨ 50 Phase 1 high-value taxonomies (insurance, legal, finance, etc.)
-
-**Improvements:**
-- 🎯 Relevance scoring (1.0 → 0.9 → 0.7 → 0.5)
-- 🔄 Backward compatibility for old taxonomies (90-day migration window)
-- 📚 Complete taxonomy documentation
-
-**Breaking Changes:**
-- None! Fully backward compatible.
-
-### v0.2.1
-
-- Initial public release
-- Multi-ad response support
-- Mock client for testing
-- Security helpers (escapeHTML, sanitizeURL)
+See [CHANGELOG.md](./CHANGELOG.md) for detailed version history.