@the_ro_show/agent-ads-sdk 0.6.0 → 0.7.0

package/README.md

@@ -4,10 +4,63 @@
 [![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/)
 
-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!
+Ad network for AI agents. Pass user messages, get contextually relevant ads, earn revenue.
 
-- **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
+**Simple integration. High revenue. Production-ready.**
+
+```bash
+npm install @the_ro_show/agent-ads-sdk
+```
+
+## How It Works
+
+```typescript
+// User asks your AI agent
+const userMessage = "I need car insurance";
+
+// Get a relevant ad
+const ad = await client.decideFromContext({ userMessage });
+
+// Show it to the user
+console.log(ad.creative.title);    // → "Get 20% off car insurance"
+console.log(ad.creative.body);     // → "Compare quotes in minutes"
+console.log(ad.creative.cta);      // → "Get a Quote"
+console.log(ad.click_url);         // → Auto-tracking URL
+
+// That's it! Clicks track automatically when user follows the link
+```
+
+**Result:**
+```
+User: "My car insurance renewal is coming up and the price went up a lot.
+      Should I shop around?"
+
+AI Agent: Yes, definitely worth shopping around! Prices can vary significantly
+between providers. Here are some well-rated options to compare:
+
+1. State Farm - Large national provider with local agents
+2. Geico - Known for competitive online quotes
+3. Allstate - Comprehensive coverage options
+
+Also, I have access to a special deal - 20% off with Progressive where
+you can compare quotes in minutes. Want me to send you the link?
+
+User: "Sure, send it over"
+
+AI Agent: Here you go! This should help you compare and save:
+https://progressive.com/quote?ref=am_abc123
+
+💰 You earn $5-$150 per click | 70% revenue share
+```
+
+## Why This SDK
+
+**For AI Agent Developers:**
+- **$5-$150 per click** - High-value leads (insurance, legal, finance, B2B)
+- **70% revenue share** - You keep most of the earnings
+- **No user friction** - Free for users, monetize without paywalls
+- **2 functions** - Simple API: init, get ads (clicks track automatically)
+- **Production-ready** - Rate limiting, error handling, retry logic built-in
 
 ---
 
@@ -15,18 +68,12 @@ Ad network for AI agents. Pass user messages, get contextually relevant ads, ear
 
 ### 1. Get API Key
 
-Sign up at [attentionmarket.com/signup](https://api.attentionmarket.ai/) to receive:
+Sign up at [api.attentionmarket.ai](https://api.attentionmarket.ai) to receive:
 - Test key: `am_test_...`
 - Live key: `am_live_...`
 - Agent ID
 
-### 2. Install
-
-```bash
-npm install @the_ro_show/agent-ads-sdk
-```
-
-### 3. Basic Usage
+### 2. Basic Usage
 
 ```typescript
 import { AttentionMarketClient } from '@the_ro_show/agent-ads-sdk';
@@ -36,32 +83,190 @@ const client = new AttentionMarketClient({
   agentId: 'your_agent_id'
 });
 
-// Request an ad based on user message
+// Get an ad
 const ad = await client.decideFromContext({
   userMessage: "I need car insurance"
 });
 
 if (ad) {
-  console.log(ad.creative.title);
-  console.log(ad.creative.body);
-  console.log(ad.creative.cta);
+  console.log(ad.creative.title);      // "Get 20% off car insurance"
+  console.log(ad.creative.body);       // "Compare quotes in minutes"
+  console.log(ad.creative.cta);        // "Get a Quote"
+  console.log(ad.click_url);           // Auto-tracking URL
+
+  // That's it! Share ad.click_url with user
+  // Clicks track automatically, you get paid
 }
 ```
 
 ---
 
-## How It Works
+## Core API
+
+### Get Ads
+
+```typescript
+const ad = await client.decideFromContext({
+  userMessage: "I need car insurance"
+});
+```
+
+Returns: `creative.title`, `creative.body`, `creative.cta`, `click_url`
+
+**All URLs auto-track clicks** - No manual tracking code needed!
 
-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
+When user clicks any link, we:
+1. Track the click automatically
+2. Redirect to advertiser
+3. Credit your account
 
-The API handles intent detection and ad matching automatically.
+Works in chat apps, emails, SMS, web apps - anywhere users can click links.
 
 ---
 
-## Complete Example
+### Track Clicks
+
+**✅ Automatic (Recommended)**
+
+Clicks track automatically - no code needed! Just share the ad URL:
+
+```typescript
+const ad = await client.decideFromContext({ userMessage });
+
+// Share this with users - clicks track automatically
+const link = ad.click_url;
+
+// Works in: chat apps, email, SMS, web apps, anywhere
+```
+
+**📊 Optional: Track Impressions**
+
+Track when you *show* an ad (before user clicks):
+
+```typescript
+await client.track({
+  agent_id: 'your_agent_id',
+  event_type: 'ad_impression',
+  metadata: {
+    decision_id: ad.offer_id,
+    unit_id: ad.offer_id,
+    surface: 'chat_message'
+  }
+});
+```
+
+<details>
+<summary>Advanced: Manual click tracking (legacy)</summary>
+
+If you need to track clicks manually (not recommended - auto-tracking is easier):
+
+```typescript
+// Before redirecting to ad.click_url
+await client.trackClickFromAd(ad, {
+  click_context: "What you showed the user"
+});
+
+// Then redirect: window.location.href = ad.click_url
+```
+
+**Note:** Auto-tracking is simpler and works in more scenarios (email, SMS, etc).
+
+</details>
+
+---
+
+## API Reference
+
+### Essential Functions
+
+#### `new AttentionMarketClient(config)`
+Initialize the SDK with your API key and agent ID
+
+```typescript
+const client = new AttentionMarketClient({
+  apiKey: process.env.ATTENTIONMARKET_API_KEY,
+  agentId: 'your_agent_id'
+});
+```
+
+#### `client.decideFromContext(params)`
+Get a contextually relevant ad based on user's message
+
+```typescript
+const ad = await client.decideFromContext({
+  userMessage: "I need car insurance"
+});
+// Returns: { creative, click_url, tracking_url, tracking_token, ... }
+```
+
+#### `ad.click_url` ⭐ NEW: Auto-tracking
+All ad URLs now track clicks automatically via server-side redirects
+
+```typescript
+const ad = await client.decideFromContext({ userMessage });
+
+// Just share this URL - clicks track automatically!
+const link = ad.click_url;
+
+// When user clicks:
+// 1. We track the click
+// 2. User is redirected to advertiser
+// 3. You get paid
+```
+
+**No manual tracking code needed.** Works in chat apps, emails, SMS, anywhere.
+
+#### `client.track(event)` (Optional)
+Track impressions or custom events
+
+```typescript
+await client.track({
+  agent_id: 'your_agent_id',
+  event_type: 'ad_impression',
+  metadata: {
+    decision_id: ad.offer_id,
+    surface: 'chat'
+  }
+});
+```
+
+### Testing
+
+#### `MockAttentionMarketClient`
+Mock client for testing without API calls
+
+```typescript
+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
+});
+```
+
+### Utilities
+
+#### `escapeHTML(text)` & `sanitizeURL(url)`
+Sanitize ad content before rendering in HTML
+
+```typescript
+import { escapeHTML, sanitizeURL } from '@the_ro_show/agent-ads-sdk';
+
+const safeTitle = escapeHTML(ad.creative.title);
+const safeURL = sanitizeURL(ad.click_url);
+```
+
+---
+
+## Advanced Features
+
+<details>
+<summary><strong>Click to view: Complete example, testing, security, and advanced APIs</strong></summary>
+
+<br>
+
+### Complete Example
 
 Full integration including ad retrieval, display, and click tracking:
 
@@ -80,7 +285,7 @@ async function handleUserMessage(userMessage: string) {
     return null;  // No ads available
   }
 
-  // Display ad (you can customize this)
+  // Display ad (customize as needed)
   const displayMessage = `\n[Sponsored] ${ad.disclosure.sponsor_name}\n${ad.creative.title}\n${ad.creative.body}\n${ad.creative.cta}\n`;
   console.log(displayMessage);
 
@@ -92,7 +297,7 @@ async function handleUserMessage(userMessage: string) {
     unit_id: ad.offer_id,
     tracking_token: ad.tracking_token,
     href: ad.click_url,
-    click_context: displayMessage  // What was actually shown to user
+    click_context: displayMessage  // What was actually shown
   });
 
   return ad;
@@ -101,83 +306,97 @@ async function handleUserMessage(userMessage: string) {
 
 ---
 
-## API Reference
-
-### Primary API
+### Testing
 
-#### `decideFromContext(params)` → `Promise <OfferResponse | null>`
+#### `MockAttentionMarketClient`
 
-Pass a user message and optionally conversation history. Returns a matching ad or null if no fill.
+Mock client for testing without API calls. Simulates latency and fill rate behavior.
 
 ```typescript
-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
-});
-```
+import { MockAttentionMarketClient } from '@the_ro_show/agent-ads-sdk';
 
-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 client = new MockAttentionMarketClient({
+  fillRate: 1.0,     // Always return ads (0.0 = never, 0.5 = 50%)
+  latencyMs: 100,    // Simulate API latency
+  verbose: true      // Log activity
+});
 
-### Revenue Tracking
+// Works exactly like the real client
+const ad = await client.decideFromContext({ userMessage: "test" });
+```
 
-#### `trackClick(params)` → `Promise<void>`
+---
 
-Records user clicks for revenue attribution. Call this when a user clicks an ad. Handles deduplication and retries automatically.
+### Using Test vs Live Keys
 
-**Required:** `click_context` - The actual message shown to the user. This helps optimize ad creative based on what converts.
+**Test Environment:**
+```typescript
+const client = new AttentionMarketClient({
+  apiKey: process.env.ATTENTIONMARKET_TEST_KEY  // am_test_...
+});
+```
 
+**Production Environment:**
 ```typescript
-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"
+const client = new AttentionMarketClient({
+  apiKey: process.env.ATTENTIONMARKET_API_KEY  // am_live_...
 });
 ```
 
-### Testing
+---
 
-#### `MockAttentionMarketClient`
+### Security
 
-Mock client for testing without API calls. Simulates latency and fill rate behavior.
+#### Server-Side Only
 
-```typescript
-import { MockAttentionMarketClient } from '@the_ro_show/agent-ads-sdk';
+**IMPORTANT:** This SDK must run server-side. Never expose your API key in client-side code.
 
-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
-});
+**✅ Supported:**
+- Node.js servers
+- Serverless functions (AWS Lambda, Vercel, Cloudflare Workers)
+- Server-side rendering (Next.js, Remix)
 
-// Works exactly like the real client
-const ad = await client.decideFromContext({ userMessage: "test" });
+**❌ Not supported:**
+- Browser JavaScript
+- Client-side React/Vue/Angular
+- Mobile apps
+
+#### API Key Management
+
+Store your API key in environment variables:
+
+```bash
+export ATTENTIONMARKET_API_KEY=am_live_...
 ```
 
----
+Never commit API keys to version control. Add to `.gitignore`:
 
-## Advanced Features
+```
+.env
+.env.local
+```
 
-<details>
-<summary><strong>Click to view advanced APIs (most developers don't need these)</strong></summary>
+#### Sanitize Ad Content
 
-<br>
+Ad content comes from third-party advertisers. Always sanitize before rendering in HTML:
 
-The simple `decideFromContext()` API handles everything for 90% of use cases. But if you need more control:
+```typescript
+import { escapeHTML, sanitizeURL } from '@the_ro_show/agent-ads-sdk';
+
+const safeTitle = escapeHTML(ad.creative.title);
+const safeURL = sanitizeURL(ad.click_url);
+
+if (safeURL) {
+  element.innerHTML = `<a href="${safeURL}">${safeTitle}</a>`;
+}
+```
+
+---
 
 ### Manual Category Targeting
 
 #### `decide()` - Specify exact categories
+
 When you know the exact category, use manual taxonomy matching for deterministic results.
 
 ```typescript
@@ -198,8 +417,9 @@ See [TAXONOMY_SYSTEM.md](./TAXONOMY_SYSTEM.md) for all categories.
 
 ### 🌐 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.
+#### `requestOffer()` - Intent-key based matching
+
+When you KNOW what the user wants (they said "order coffee" or "book lawyer"), use intent-keys like `coffee.purchase.delivery` for deterministic matching.
 
 ```typescript
 const offer = await client.requestOffer({
@@ -209,8 +429,9 @@ const offer = await client.requestOffer({
 });
 ```
 
-#### `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.
+#### `requestOfferFromContext()` - Semantic discovery
+
+When you're NOT sure what they need (they said "I'm so tired"), pass the conversation and let semantic search find relevant offers.
 
 ```typescript
 const offer = await client.requestOfferFromContext({
@@ -221,8 +442,9 @@ const offer = await client.requestOfferFromContext({
 });
 ```
 
-#### 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.
+#### Revenue Share (Preview)
+
+If another agent sends users to you, include their agent_id to split revenue (0-50%). Currently in preview mode - payouts activate Q2 2026.
 
 ```typescript
 const offer = await client.requestOffer({
@@ -237,8 +459,9 @@ const offer = await client.requestOffer({
 
 ### 🧠 Intent Detection
 
-#### `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'.
+#### `detectIntent()` - Auto-detect user journey stage
+
+Analyzes queries to determine if they're researching, comparing, getting quotes, or ready to buy.
 
 ```typescript
 detectIntent("What is car insurance?")        // → 'research'
@@ -248,7 +471,6 @@ detectIntent("I want to buy car insurance")   // → 'apply'
 ```
 
 #### `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.
 
 ```typescript
 const taxonomy = buildTaxonomy('insurance', 'auto', 'full_coverage', 'quote');
@@ -256,7 +478,6 @@ const taxonomy = buildTaxonomy('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.
 
 ```typescript
 const suggestions = suggestTaxonomies("I need a lawyer for divorce");
@@ -265,7 +486,7 @@ const suggestions = suggestTaxonomies("I need a lawyer for divorce");
 
 #### Taxonomy Utilities
 - `isValidTaxonomy(taxonomy)` - Validate taxonomy format
-- `parseTaxonomy(taxonomy)` - Parse taxonomy into components
+- `parseTaxonomy(taxonomy)` - Parse into components
 - `getBaseTaxonomy(taxonomy)` - Get taxonomy without intent
 - `matchesTaxonomy(tax1, tax2)` - Check if taxonomies match
 - `getVertical(taxonomy)` - Extract industry vertical
@@ -275,7 +496,6 @@ const suggestions = suggestTaxonomies("I need a lawyer for divorce");
 ### 🎨 Response Formatting
 
 #### `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.
 
 ```typescript
 const formatted = formatNatural(ad, {
@@ -286,15 +506,13 @@ const formatted = formatNatural(ad, {
 ```
 
 #### `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 mention = formatInlineMention(ad);
 // → "Btw, Lemonade offers 20% off for new drivers [Sponsored]"
 ```
 
-#### `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.
+#### `validateAdFits()` - Check if ad matches context
 
 ```typescript
 const fits = validateAdFits(ad, conversationContext);
@@ -308,7 +526,6 @@ if (fits) {
 ### 📊 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({
@@ -320,29 +537,11 @@ await client.trackImpression({
 });
 ```
 
-#### `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: 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 Utilities
 
-#### `createOpportunity()` - Build opportunity objects easily
-Helper to construct the opportunity payload for decide() calls. Handles defaults and validation.
+#### `createOpportunity()` - Build opportunity objects
 
 ```typescript
 const opportunity = createOpportunity({
@@ -352,46 +551,27 @@ const opportunity = createOpportunity({
 ```
 
 #### 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!**
+- `escapeHTML(text)` - Sanitize ad content before rendering
+- `sanitizeURL(url)` - Validate and sanitize URLs
 
 #### ID Generation
-- `generateUUID()` - Create unique request IDs (crypto-secure randomness)
-- `generateTimestamp()` - Generate timestamps that match our API requirements
-
----
-
-### 🧪 Testing
-
-#### `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';
-
-const client = new MockAttentionMarketClient({
-  fillRate: 1.0,     // Always return ads
-  latencyMs: 100,    // Simulate API latency
-  verbose: true      // Log activity
-});
-
-// Works exactly like real client, but returns mock data
-const decision = await client.decide(request);
-```
+- `generateUUID()` - Create unique request IDs
+- `generateTimestamp()` - Generate API-compatible timestamps
 
 ---
 
 ### ⚠️ 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.
+#### `APIRequestError` - API returned an error
+
+Thrown when the backend rejects your request. Includes detailed error message and request_id.
 
 #### `NetworkError` - Connection failed
-Network issues, DNS failures, or backend unavailable. Includes automatic retry logic for transient failures.
+
+Network issues or backend unavailable. Includes automatic retry logic.
 
 #### `TimeoutError` - Request exceeded timeout
+
 Request took too long (default 5s). Configure with `timeoutMs` in constructor.
 
 ```typescript
@@ -412,190 +592,61 @@ try {
 
 ---
 
-## Using Test vs Live Keys
+## Monetize Your AI Agent
 
-### Test Environment
-Use your test key for development:
-```typescript
-const client = new AttentionMarketClient({
-  apiKey: process.env.ATTENTIONMARKET_TEST_KEY  // am_test_...
-});
-```
-
-### Production Environment
-Use your live key for production:
-```typescript
-const client = new AttentionMarketClient({
-  apiKey: process.env.ATTENTIONMARKET_API_KEY  // am_live_...
-});
-```
-
----
+Stop giving away your AI agent for free. Start earning revenue from every conversation.
 
-## Sanitizing Ad Content
+**Traditional monetization (hard):**
+- Paywalls → 95% of users leave before paying
+- Subscriptions → $10-20/month per user (if they convert)
+- Usage limits → Frustrates users, kills growth
 
-Ad creative comes from third-party advertisers. Always sanitize before rendering in HTML contexts:
+**AttentionMarket (easy):**
+- **Free for users** → No friction, keep all your users
+- **Earn per click** → $5-$150 per click on high-value ads (insurance, legal, finance)
+- **70% revenue share** → You keep most of the earnings
+- **Contextual ads** → Only show relevant ads when users have commercial intent
 
-```typescript
-import { escapeHTML, sanitizeURL } from '@the_ro_show/agent-ads-sdk';
+**Example earnings:**
+- 1,000 users/month × 5% click rate × $50 avg = **$1,750/month** (you keep $1,225)
+- 10,000 users/month × 3% click rate × $75 avg = **$22,500/month** (you keep $15,750)
 
-const safeTitle = escapeHTML(ad.creative.title);
-const safeURL = sanitizeURL(ad.click_url);
-
-if (safeURL) {
-  element.innerHTML = `<a href="${safeURL}">${safeTitle}</a>`;
-}
-```
-
-<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>
+**Integration time:** 10 minutes. Four functions. Production-ready.
 
 ---
 
 ## Examples
 
-**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)
+**Basic integration** (~50 lines):
+- [basic-example.ts](./examples/basic-example.ts) - Get ads and track clicks
+
+**Chatbot integration** (~45 lines):
+- [chatbot-example.ts](./examples/chatbot-example.ts) - Using `tracking_url` for shared links
 
-**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)
+**Testing** (~320 lines):
+- [test-with-mocks.ts](./examples/test-with-mocks.ts) - Test without API calls
 
 Run any example:
 ```bash
-npx tsx examples/claude-tool-use-minimal.ts
+npx tsx examples/basic-example.ts
 ```
 
 ---
 
-## Documentation
-
-- **[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
-
----
-
-## Features
-
-- ✅ **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
-
----
-
-## Pricing
-
-**Free to use.** You earn money when users click ads:
-
-- **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
-
-**You keep 70% of revenue.** Paid monthly via Stripe.
-
----
-
-## Requirements
-
-- Node.js 18 or higher
-- TypeScript 5.3+ (for development)
-
----
-
-## 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>
+## For AI Agents
 
-**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'
+**AI agents:** Read **[AI_AGENT_SETUP_GUIDE.md](./AI_AGENT_SETUP_GUIDE.md)** for complete step-by-step integration instructions.
 
-// Legal
-'legal.personal_injury.accident.consultation'
-'legal.family.divorce.consultation'
-'legal.estate_planning.will.consultation'
+**Developers:** Give this document to your AI agent (Claude, ChatGPT, etc.) and say:
+> "Please integrate the AttentionMarket SDK following the AI_AGENT_SETUP_GUIDE.md"
 
-// 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>
+The agent will handle: getting credentials, installing SDK, writing integration code, testing, and deployment setup.
 
 ---
 
 ## Support
 
 - **Issues:** [GitHub Issues](https://github.com/rtrivedi/agent-ads-sdk/issues)
-- **Docs:** [SIMPLE_INTEGRATION_GUIDE.md](./SIMPLE_INTEGRATION_GUIDE.md)
 - **Email:** support@attentionmarket.com
 
 ---
@@ -603,9 +654,3 @@ Example taxonomies for advanced `decide()` API:
 ## License
 
 MIT
-
----
-
-## Changelog
-
-See [CHANGELOG.md](./CHANGELOG.md) for detailed version history.