@the_ro_show/agent-ads-sdk 0.4.0 → 0.4.2

package/README.md

@@ -1,553 +1,474 @@
 # AttentionMarket Agent Ads SDK
 
-TypeScript SDK for integrating agent-native sponsored units (Sponsored Suggestions and Sponsored Tools) into AI agents.
+[![npm version](https://badge.fury.io/js/@the_ro_show%2Fagent-ads-sdk.svg)](https://www.npmjs.com/package/@the_ro_show/agent-ads-sdk)
+[![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/)
 
-## 🚀 New to this? Start Here
+**The first ad network built for AI agents.** Monetize your AI agent with contextual, high-intent sponsored suggestions. Open source, transparent, developer-first.
 
-**→ [Simple Integration Guide](./SIMPLE_INTEGRATION_GUIDE.md)** - Step-by-step guide for Clawdbot/Moltbot developers
+- 🚀 **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
 
-This README contains the full API reference. If you're just getting started, the Simple Integration Guide is much easier to follow!
-
----
+## Quick Start
 
-## Installation
+### 1. Get Your API Key
 
-```bash
-npm install @the_ro_show/agent-ads-sdk
-```
+**Sign up at [attentionmarket.com/signup](https://attentionmarket.com/signup)** (30 seconds, free forever)
 
-## Configuration
+You'll receive:
+- Test key: `am_test_...` (for development)
+- Live key: `am_live_...` (for production)
 
-Store your credentials in environment variables:
+### 2. Install
 
 ```bash
-export ATTENTIONMARKET_API_KEY=am_live_...
-export ATTENTIONMARKET_AGENT_ID=agt_01HV...
+npm install @the_ro_show/agent-ads-sdk
 ```
 
-**⚠️ Never commit API keys to version control.** See [SECURITY.md](./SECURITY.md) for best practices.
-
-## Quick Start
+### 3. Integrate (5 lines of code)
 
 ```typescript
-import { AttentionMarketClient, createOpportunity, generateUUID } from '@the_ro_show/agent-ads-sdk';
-
-const client = new AttentionMarketClient({ apiKey: process.env.ATTENTIONMARKET_API_KEY });
+import { AttentionMarketClient, detectIntent, buildTaxonomy } from '@the_ro_show/agent-ads-sdk';
 
-const opportunity = createOpportunity({
-  taxonomy: 'local_services.movers.quote',
-  country: 'US',
-  language: 'en',
-  platform: 'web',
-  query: 'Find movers in Brooklyn',
+const client = new AttentionMarketClient({
+  apiKey: process.env.ATTENTIONMARKET_API_KEY  // Your test or live key
 });
 
-const unit = await client.decide({
-  request_id: generateUUID(),
-  agent_id: process.env.ATTENTIONMARKET_AGENT_ID,
-  placement: { type: 'sponsored_suggestion', surface: 'chat_response' },
-  opportunity,
+// 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' }
+  }
 });
 
-if (unit && unit.unit_type === 'sponsored_suggestion') {
-  console.log(`[${unit.disclosure.label}] ${unit.disclosure.sponsor_name}`);
-  console.log(unit.suggestion.title);
-
-  await client.trackImpression({
-    agent_id: process.env.ATTENTIONMARKET_AGENT_ID,
-    request_id: 'req_id',
-    decision_id: 'decision_id',
-    unit_id: unit.unit_id,
-    tracking_token: unit.tracking.token,
-  });
+if (decision.status === 'filled') {
+  const ad = decision.units[0];
+  console.log(`[Sponsored] ${ad.suggestion.title}`);
+  // User clicks → You earn $5-50
 }
 ```
 
-## Security Best Practices
-
-🔴 **CRITICAL SECURITY REQUIREMENTS**
+**That's it!** Start earning from relevant ads.
 
-### 1. Server-Side Only
-
-**This SDK MUST only be used server-side.** Your API key provides full access to your account and billing.
+---
 
-✅ **Safe:** Node.js, serverless functions, server-side rendering
-❌ **Unsafe:** Browser JavaScript, mobile apps without backend proxy
+## 🆕 What's New in v0.4.0
 
-### 2. Sanitize Ad Content Before Display
+### Hierarchical Taxonomy Matching
 
-Ad content can contain malicious HTML/JavaScript. **Always sanitize** before rendering in HTML:
+Target broadly, match specifically:
 
 ```typescript
-import { escapeHTML, sanitizeURL } from '@the_ro_show/agent-ads-sdk';
+// Advertiser targets: "insurance.auto"
+// Your agent requests: "insurance.auto.full_coverage.quote"
+// ✅ Matches! (0.7 relevance score)
 
-// ✅ SAFE: Sanitize content
-const safeTitle = escapeHTML(unit.suggestion.title);
-const safeBody = escapeHTML(unit.suggestion.body);
-const safeURL = sanitizeURL(unit.suggestion.action_url);
+// Your agent requests: "insurance.auto.liability.compare"
+// ✅ Also matches! (0.7 relevance score)
 
-if (safeURL) {
-  element.innerHTML = `<a href="${safeURL}">${safeTitle}</a>`;
-}
+// Your agent requests: "insurance.home.flood.quote"
+// ❌ No match (different category)
 ```
 
-```typescript
-// ❌ DANGEROUS: Direct HTML injection (XSS vulnerability!)
-element.innerHTML = unit.suggestion.title;
-```
+**Result:** 3x more ad inventory, higher fill rates.
 
-### 3. Validate URLs
-
-Always validate `action_url` before using:
+### New Helper Functions
 
+**Auto-detect user intent:**
 ```typescript
-const safeURL = sanitizeURL(unit.suggestion.action_url);
+import { detectIntent } from '@the_ro_show/agent-ads-sdk';
 
-if (!safeURL) {
-  console.error('Dangerous URL blocked');
-  return; // Don't render the ad
-}
+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'
 ```
 
-Blocks dangerous protocols: `javascript:`, `data:`, `file:`
-
-### 4. See Complete Guidelines
+**Build taxonomies easily:**
+```typescript
+import { buildTaxonomy } from '@the_ro_show/agent-ads-sdk';
 
-📖 **[Read SECURITY.md](./SECURITY.md)** for comprehensive security guidelines including:
-- XSS prevention examples
-- Phishing protection
-- Rate limiting
-- Input validation
-- Security checklist
+const taxonomy = buildTaxonomy('insurance', 'auto', 'full_coverage', 'quote');
+// → "insurance.auto.full_coverage.quote"
+```
 
-## Testing Without Advertiser Data
+**Get taxonomy suggestions:**
+```typescript
+import { suggestTaxonomies } from '@the_ro_show/agent-ads-sdk';
 
-Use `MockAttentionMarketClient` to test your integration without needing real ad campaigns.
+const suggestions = suggestTaxonomies("I need a lawyer for divorce");
+// → ['legal.family.divorce.consultation', 'legal.family.custody.consultation']
+```
 
+**Validate taxonomies:**
 ```typescript
-import { MockAttentionMarketClient, createOpportunity, generateUUID } from '@the_ro_show/agent-ads-sdk';
+import { isValidTaxonomy, parseTaxonomy } from '@the_ro_show/agent-ads-sdk';
 
-// Use mock client during development
-const client = new MockAttentionMarketClient({
-  latencyMs: 100,    // Simulate API latency
-  fillRate: 1.0,     // 100% fill rate for testing
-  verbose: true,     // Log mock activity
-});
-
-const opportunity = createOpportunity({
-  taxonomy: 'local_services.movers.quote',
-  country: 'US',
-  language: 'en',
-  platform: 'web',
-  query: 'Find movers in Brooklyn',
-});
+isValidTaxonomy('insurance.auto.full_coverage.quote')  // → true
+isValidTaxonomy('invalid.format')                      // → false
 
-const unit = await client.decide({
-  request_id: generateUUID(),
-  agent_id: 'agt_test',
-  placement: { type: 'sponsored_suggestion', surface: 'chat_response' },
-  opportunity,
-});
-
-// Returns realistic mock ad data immediately
-if (unit && unit.unit_type === 'sponsored_suggestion') {
-  console.log(unit.suggestion.title); // "Professional Moving Services - Same Day Available"
-}
+const parsed = parseTaxonomy('insurance.auto.full_coverage.quote');
+// → { vertical: 'insurance', category: 'auto', subcategory: 'full_coverage', intent: 'quote' }
 ```
 
-**Available mock taxonomies:**
-- `local_services.movers.quote`
-- `local_services.restaurants.search`
-- `local_services.plumbers.quote`
-- `local_services.electricians.quote`
-- `local_services.cleaners.quote`
-- `shopping.electronics.search`
+---
 
-**Add custom mock ads:**
+## Common Taxonomies
 
+### Insurance ($20-54 CPC)
 ```typescript
-client.addMockUnit('your.custom.taxonomy', {
-  unit_id: 'unit_custom_001',
-  unit_type: 'sponsored_suggestion',
-  disclosure: { label: 'Sponsored', sponsor_name: 'Your Sponsor' },
-  tracking: { token: 'trk_test', impression_url: '...', click_url: '...' },
-  suggestion: {
-    title: 'Your Ad Title',
-    body: 'Your ad body text',
-    cta: 'Call to Action',
-    action_url: 'https://example.com',
-  },
-});
+'insurance.auto.full_coverage.quote'
+'insurance.auto.liability.compare'
+'insurance.home.standard.quote'
+'insurance.life.term.compare'
+'insurance.health.individual.quote'
 ```
 
-**Run the full test suite:**
-
-```bash
-npx tsx examples/test-with-mocks.ts
+### 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'
 ```
 
-**Switch to production:**
-
+### Financial Services ($15-50 CPC)
 ```typescript
-const client = process.env.NODE_ENV === 'production'
-  ? new AttentionMarketClient({ apiKey: process.env.ATTENTIONMARKET_API_KEY })
-  : new MockAttentionMarketClient();
+'financial.loans.personal.quote'
+'financial.loans.mortgage.compare'
+'financial.credit_cards.rewards.compare'
+'financial.investing.brokerage.trial'
 ```
 
-## Agent Integration Examples
-
-### Minimal Examples (< 80 lines)
-
-Start here for a quick overview:
-
-- **[Claude](./examples/claude-tool-use-minimal.ts)** - Minimal tool use integration
-- **[OpenAI GPT](./examples/openai-function-calling-minimal.ts)** - Minimal function calling
-- **[Google Gemini](./examples/gemini-function-calling-minimal.ts)** - Minimal function declarations
-
-Each shows: `createOpportunity` → `decide` → render → track
-
-### Full Examples (with detailed integration notes)
+### B2B SaaS ($10-100 CPC)
+```typescript
+'business.saas.crm.trial'
+'business.saas.project_management.trial'
+'business.ecommerce.platform.trial'
+'business.saas.marketing_automation.trial'
+```
 
-For production integrations:
+### Home Services ($5-30 CPC)
+```typescript
+'home_services.moving.local.quote'
+'home_services.cleaning.regular.book'
+'home_services.plumbing.emergency.quote'
+'home_services.remodeling.kitchen.quote'
+```
 
-- **[Claude (Anthropic)](./examples/claude-tool-use-full.ts)** - Complete tool use pattern with schemas and tracking
-- **[OpenAI GPT](./examples/openai-function-calling-full.ts)** - Complete function calling with integration checklist
-- **[Google Gemini](./examples/gemini-function-calling-full.ts)** - Complete function declarations with testing guide
-- **[Safe Web Rendering](./examples/safe-web-rendering.ts)** - XSS prevention and secure HTML rendering
+**See all 50+ taxonomies:** [TAXONOMY_SYSTEM.md](./TAXONOMY_SYSTEM.md)
 
-Run any example with:
-```bash
-npx tsx examples/claude-tool-use-minimal.ts
-npx tsx examples/safe-web-rendering.ts
-```
+---
 
-## Full Example with Raw Response
+## Complete Example
 
 ```typescript
 import {
   AttentionMarketClient,
-  createOpportunity,
-  generateUUID,
+  buildTaxonomy,
+  detectIntent
 } from '@the_ro_show/agent-ads-sdk';
 
 const client = new AttentionMarketClient({
-  apiKey: process.env.ATTENTIONMARKET_API_KEY,
+  apiKey: process.env.ATTENTIONMARKET_API_KEY
 });
 
-// Build opportunity
-const opportunity = createOpportunity({
-  taxonomy: 'local_services.movers.quote',
-  country: 'US',
-  language: 'en',
-  platform: 'web',
-  query: 'Find movers in Brooklyn',
-});
+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
+  }
 
-// Get full response (includes status, ttl_ms, all units)
-const response = await client.decideRaw({
-  request_id: generateUUID(),
-  agent_id: process.env.ATTENTIONMARKET_AGENT_ID,
-  placement: {
-    type: 'sponsored_suggestion',
-    surface: 'chat_response',
-  },
-  opportunity,
-});
+  // 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'
+      }
+    }
+  });
 
-if (response.status === 'filled') {
-  // Access all units and metadata
-  console.log(`TTL: ${response.ttl_ms}ms`);
-  console.log(`Units: ${response.units.length}`);
+  // 4. Show ad if available
+  if (decision.status === 'filled') {
+    const ad = decision.units[0];
 
-  const unit = response.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`);
 
-  // Render unit
-  if (unit && unit.unit_type === 'sponsored_suggestion') {
-    console.log(unit.suggestion.title);
-  }
+    // 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
+    });
 
-  // Track impression after rendering
-  await client.trackImpression({
-    agent_id: process.env.ATTENTIONMARKET_AGENT_ID,
-    request_id: response.request_id,
-    decision_id: response.decision_id,
-    unit_id: unit.unit_id,
-    tracking_token: unit.tracking.token,
-    metadata: { surface: 'chat_response' },
-  });
+    // 6. Track click when user clicks (you earn money!)
+    // await client.trackClick({ ... });
 
-  // Track click when user clicks
-  await client.trackClick({
-    agent_id: process.env.ATTENTIONMARKET_AGENT_ID,
-    request_id: response.request_id,
-    decision_id: response.decision_id,
-    unit_id: unit.unit_id,
-    tracking_token: unit.tracking.token,
-    href: unit.suggestion.action_url,
-  });
+    return ad;
+  }
+
+  return null; // No ads available
 }
+
+// Example usage
+await showRelevantAd("I need car insurance for my Honda");
+await showRelevantAd("I need a divorce lawyer in California");
 ```
 
-## API Methods
+---
 
-### `decide(request, options?): Promise<AdUnit | null>`
+## API Reference
 
-Convenience method that returns the first ad unit or `null` if no fill.
+### Client Methods
 
+**`client.decide(request)`** - Get ads (convenience method)
 ```typescript
-const unit = await client.decide({
-  request_id: generateUUID(),
-  agent_id: process.env.ATTENTIONMARKET_AGENT_ID,
-  placement: {
-    type: 'sponsored_suggestion',
-    surface: 'chat_response',
-  },
-  opportunity,
+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' }
+  }
 });
 ```
 
-### `decideRaw(request, options?): Promise<DecideResponse>`
-
-Returns the full response including status, ttl_ms, and all units.
-
+**`client.decideRaw(request)`** - Get full response with metadata
 ```typescript
-const response = await client.decideRaw({
-  request_id: generateUUID(),
-  agent_id: process.env.ATTENTIONMARKET_AGENT_ID,
-  placement: { type: 'sponsored_suggestion', surface: 'chat_response' },
-  opportunity,
-}, {
-  idempotencyKey: 'optional-idempotency-key',
-});
+const response = await client.decideRaw(request);
+// Returns: { status, request_id, decision_id, units[], ttl_ms }
 ```
 
-### `trackImpression(params): Promise<EventIngestResponse>`
-
-Convenience method to track when a unit is rendered.
-
+**`client.trackImpression(params)`** - Track when ad is shown
 ```typescript
 await client.trackImpression({
-  agent_id: process.env.ATTENTIONMARKET_AGENT_ID,
+  agent_id: 'your_agent_id',
   request_id: 'req_123',
   decision_id: 'dec_456',
   unit_id: 'unit_789',
-  tracking_token: 'trk_abc',
-  metadata: { surface: 'chat_response' },
+  tracking_token: 'trk_abc'
 });
 ```
 
-### `trackClick(params): Promise<EventIngestResponse>`
-
-Convenience method to track when a user clicks a unit.
-
+**`client.trackClick(params)`** - Track when ad is clicked (you earn $)
 ```typescript
 await client.trackClick({
-  agent_id: process.env.ATTENTIONMARKET_AGENT_ID,
+  agent_id: 'your_agent_id',
   request_id: 'req_123',
   decision_id: 'dec_456',
   unit_id: 'unit_789',
   tracking_token: 'trk_abc',
-  href: 'https://example.com/action',
+  href: 'https://advertiser.com'
 });
 ```
 
-### `track(event): Promise<EventIngestResponse>`
+### Helper Functions
 
-Low-level method to track any event type.
+- `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
 
-```typescript
-await client.track({
-  event_id: generateUUID(),
-  occurred_at: new Date().toISOString(),
-  agent_id: process.env.ATTENTIONMARKET_AGENT_ID,
-  request_id: 'req_123',
-  decision_id: 'dec_456',
-  unit_id: 'unit_789',
-  event_type: 'impression',
-  tracking_token: 'trk_abc',
-});
-```
+### Security Helpers
 
-### `getPolicy(): Promise<PolicyResponse>`
+- `escapeHTML(text)` - Escape HTML to prevent XSS
+- `sanitizeURL(url)` - Validate and sanitize URLs
 
-Fetch policy constraints and formatting requirements.
+**Always sanitize ad content before rendering!**
 
-```typescript
-const policy = await client.getPolicy();
-console.log(policy.defaults.max_units_per_response);
-console.log(policy.disclosure.label);
-```
+---
 
-### `signupAgent(request, options?): Promise<AgentSignupResponse>` (static)
+## Testing
 
-Register a new agent (unauthenticated endpoint).
+### Mock Client (No API calls)
 
 ```typescript
-const signup = await AttentionMarketClient.signupAgent({
-  owner_email: 'owner@company.com',
-  agent_name: 'My Agent',
-  sdk: 'typescript',
-  environment: 'test',
+import { MockAttentionMarketClient } from '@the_ro_show/agent-ads-sdk';
+
+const client = new MockAttentionMarketClient({
+  fillRate: 1.0,     // Always return ads
+  latencyMs: 100,    // Simulate API latency
+  verbose: true      // Log activity
 });
 
-console.log(signup.agent_id);
-console.log(signup.api_key);
+// Works exactly like real client, but returns mock data
+const decision = await client.decide(request);
 ```
 
-## Helper Functions
-
-### `createOpportunity(params): Opportunity`
-
-Build a valid Opportunity object with safe defaults.
+### Test Taxonomies
 
+Use your test key with real API:
 ```typescript
-const opportunity = createOpportunity({
-  // Required
-  taxonomy: 'local_services.movers.quote',
-  country: 'US',
-  language: 'en',
-  platform: 'web',
-
-  // Optional
-  query: 'Find movers in Brooklyn',
-  region: 'NY',
-  city: 'New York',
-
-  // Optional overrides (with defaults shown)
-  constraints: {
-    max_units: 1,
-    allowed_unit_types: ['sponsored_suggestion'],
-    blocked_categories: ['adult'],
-  },
-  privacy: {
-    data_policy: 'coarse_only',
-  },
+const client = new AttentionMarketClient({
+  apiKey: process.env.ATTENTIONMARKET_TEST_KEY  // am_test_...
 });
 ```
 
-### `createImpressionEvent(params): EventIngestRequest`
+---
 
-Build an impression event payload.
+## Security
 
-```typescript
-import { createImpressionEvent } from '@the_ro_show/agent-ads-sdk';
+### ⚠️ CRITICAL: Server-Side Only
 
-const event = createImpressionEvent({
-  agent_id: process.env.ATTENTIONMARKET_AGENT_ID,
-  request_id: 'req_123',
-  decision_id: 'dec_456',
-  unit_id: 'unit_789',
-  tracking_token: 'trk_abc',
-  occurred_at: new Date().toISOString(), // optional, auto-generated
-  metadata: { surface: 'chat_response' }, // optional
-});
+**Never use this SDK in browsers or mobile apps.** Your API key has full access to your account.
 
-await client.track(event);
-```
+✅ **Safe:** Node.js, serverless functions, server-side rendering
+❌ **Unsafe:** Browser JavaScript, React/Vue components, mobile apps
 
-### `createClickEvent(params): EventIngestRequest`
+### Sanitize Ad Content
 
-Build a click event payload.
+Always escape ad content before rendering:
 
 ```typescript
-import { createClickEvent } from '@the_ro_show/agent-ads-sdk';
+import { escapeHTML, sanitizeURL } from '@the_ro_show/agent-ads-sdk';
 
-const event = createClickEvent({
-  agent_id: process.env.ATTENTIONMARKET_AGENT_ID,
-  request_id: 'req_123',
-  decision_id: 'dec_456',
-  unit_id: 'unit_789',
-  tracking_token: 'trk_abc',
-  href: 'https://example.com',
-  occurred_at: new Date().toISOString(), // optional, auto-generated
-});
+const safeTitle = escapeHTML(ad.suggestion.title);
+const safeURL = sanitizeURL(ad.suggestion.action_url);
 
-await client.track(event);
+if (safeURL) {
+  element.innerHTML = `<a href="${safeURL}">${safeTitle}</a>`;
+}
 ```
 
-### `generateUUID(): string`
+**See [SECURITY.md](./SECURITY.md) for complete guidelines.**
 
-Generate a UUID v4 for request_id, event_id, etc.
+---
 
-```typescript
-import { generateUUID } from '@the_ro_show/agent-ads-sdk';
+## Examples
 
-const requestId = generateUUID();
-```
+**Minimal integrations** (< 80 lines):
+- [Claude Tool Use](./examples/claude-tool-use-minimal.ts)
+- [OpenAI Function Calling](./examples/openai-function-calling-minimal.ts)
+- [Google Gemini](./examples/gemini-function-calling-minimal.ts)
 
-### `escapeHTML(text): string`
+**Full integrations** (production-ready):
+- [Claude Complete](./examples/claude-tool-use-full.ts)
+- [OpenAI Complete](./examples/openai-function-calling-full.ts)
+- [Safe Web Rendering](./examples/safe-web-rendering.ts)
 
-Escape HTML special characters to prevent XSS attacks.
+Run any example:
+```bash
+npx tsx examples/claude-tool-use-minimal.ts
+```
 
-```typescript
-import { escapeHTML } from '@the_ro_show/agent-ads-sdk';
+---
 
-const safeTitle = escapeHTML(unit.suggestion.title);
-element.innerHTML = safeTitle; // Safe from XSS
-```
+## Documentation
 
-Escapes: `&`, `<`, `>`, `"`, `'`, `/`
+- **[Simple Integration Guide](./SIMPLE_INTEGRATION_GUIDE.md)** - Step-by-step for beginners
+- **[Taxonomy System](./TAXONOMY_SYSTEM.md)** - Complete taxonomy reference
+- **[Migration Guide](./TAXONOMY_MIGRATION_GUIDE.md)** - Upgrading from older versions
+- **[Security Guide](./SECURITY.md)** - Security best practices
+- **[Advertiser Guide](./ADVERTISER_ONBOARDING_GUIDE.md)** - For advertisers
 
-### `sanitizeURL(url, options?): string | null`
+---
 
-Validate and sanitize URLs to prevent XSS and phishing attacks.
+## Features
 
-```typescript
-import { sanitizeURL } from '@the_ro_show/agent-ads-sdk';
+- ✅ **Hierarchical matching** - Advertisers target broadly, agents match specifically
+- ✅ **Auto-intent detection** - Automatically detect research vs quote vs apply
+- ✅ **50+ high-value taxonomies** - Insurance, legal, finance, B2B SaaS, and more
+- ✅ **TypeScript support** - Full type definitions included
+- ✅ **Automatic retries** - Exponential backoff for failed requests
+- ✅ **Mock client** - Test without API calls
+- ✅ **Security helpers** - XSS protection, URL sanitization
+- ✅ **Zero dependencies** - No external runtime dependencies
 
-const safeURL = sanitizeURL(unit.suggestion.action_url);
+---
 
-if (safeURL) {
-  window.open(safeURL, '_blank');
-} else {
-  console.error('Dangerous URL blocked');
-}
-```
+## Pricing
 
-**Blocked protocols:** `javascript:`, `data:`, `file:`, `vbscript:`
+**Free to use.** You earn money when users click ads:
 
-**Options:**
-- `allowHttp: boolean` - Allow HTTP URLs (default: false, HTTPS only)
-- `allowTel: boolean` - Allow tel: links (default: true)
-- `allowMailto: boolean` - Allow mailto: links (default: true)
+- **Insurance:** $20-54 per click
+- **Legal:** $50-150 per click
+- **Financial:** $15-50 per click
+- **B2B SaaS:** $10-100 per click
+- **Home Services:** $5-30 per click
 
-## Features
+**You keep 70% of revenue.** Paid monthly via Stripe.
 
-- ✅ TypeScript support with full type definitions
-- ✅ Automatic retries with exponential backoff
-- ✅ Configurable timeouts (default 4000ms)
-- ✅ Idempotency support
-- ✅ Discriminated union types for type-safe ad units
-- ✅ Helper functions for common operations
-- ✅ No external runtime dependencies (Node.js 18+)
+---
 
 ## Requirements
 
 - Node.js 18 or higher
-- TypeScript 5.3 or higher (for development)
+- TypeScript 5.3+ (for development)
 
-## Error Handling
+---
 
-The SDK throws typed errors that include full API context:
+## Support
 
-```typescript
-import { APIRequestError, NetworkError, TimeoutError } from '@the_ro_show/agent-ads-sdk';
-
-try {
-  const unit = await client.decide(request);
-} catch (error) {
-  if (error instanceof APIRequestError) {
-    console.error(`API Error [${error.statusCode}]: ${error.errorCode}`);
-    console.error(`Message: ${error.message}`);
-    console.error(`Request ID: ${error.requestId}`);
-  } else if (error instanceof TimeoutError) {
-    console.error('Request timed out');
-  } else if (error instanceof NetworkError) {
-    console.error('Network error:', error.message);
-  }
-}
-```
+- **Issues:** [GitHub Issues](https://github.com/rtrivedi/agent-ads-sdk/issues)
+- **Docs:** [SIMPLE_INTEGRATION_GUIDE.md](./SIMPLE_INTEGRATION_GUIDE.md)
+- **Email:** support@attentionmarket.com
+
+---
 
 ## License
 
 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)