@the_ro_show/agent-ads-sdk 0.7.0 → 0.9.0

package/README.md

@@ -1,656 +1,462 @@
-# AttentionMarket Agent Ads SDK
+# AttentionMarket
 
 [![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/)
 
-Ad network for AI agents. Pass user messages, get contextually relevant ads, earn revenue.
+**The ad exchange for the AI era. Monetize your chatbot, AI assistant, or AI agent with one API call.**
 
-**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
+Works on every platform — iOS, Android, Web, Voice, Discord, WhatsApp, Node.js, Python, and anything else that can make an HTTP request.
 
 ---
 
-## Quick Start
+## Two Ways To Earn
 
-### 1. Get API Key
+### 1. Show ads in your chatbot or AI assistant
+Your app has conversations. Users ask questions. You send us the context, we return a relevant ad, you earn $5–$150 when the user clicks.
 
-Sign up at [api.attentionmarket.ai](https://api.attentionmarket.ai) to receive:
-- Test key: `am_test_...`
-- Live key: `am_live_...`
-- Agent ID
-
-### 2. Basic Usage
-
-```typescript
-import { AttentionMarketClient } from '@the_ro_show/agent-ads-sdk';
-
-const client = new AttentionMarketClient({
-  apiKey: process.env.ATTENTIONMARKET_API_KEY,
-  agentId: 'your_agent_id'
-});
-
-// Get an ad
-const ad = await client.decideFromContext({
-  userMessage: "I need car insurance"
-});
-
-if (ad) {
-  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
-}
-```
+### 2. List your AI agent on the exchange
+You built a specialized AI agent. Other AI agents need what you offer. List it on AttentionMarket and earn every time another agent calls yours.
 
 ---
 
-## Core API
+## Quick Start — 30 Seconds
 
-### Get Ads
+Get your API keys at [api.attentionmarket.ai](https://api.attentionmarket.ai), then:
 
-```typescript
-const ad = await client.decideFromContext({
-  userMessage: "I need car insurance"
-});
+```bash
+curl -X POST https://peruwnbrqkvmrldhpoom.supabase.co/functions/v1/decide \
+  -H "X-AM-API-Key: am_live_YOUR_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"context": "I need car insurance"}'
+```
+
+**Response:**
+```json
+{
+  "status": "filled",
+  "units": [{
+    "suggestion": {
+      "title": "Get 20% off car insurance",
+      "body": "Compare quotes in minutes",
+      "cta": "Get a Quote",
+      "tracking_url": "https://..."
+    }
+  }]
+}
 ```
 
-Returns: `creative.title`, `creative.body`, `creative.cta`, `click_url`
-
-**All URLs auto-track clicks** - No manual tracking code needed!
-
-When user clicks any link, we:
-1. Track the click automatically
-2. Redirect to advertiser
-3. Credit your account
-
-Works in chat apps, emails, SMS, web apps - anywhere users can click links.
+Show `suggestion.title` and `suggestion.body` to your user. When they click, send them to `tracking_url`. That's it — you get paid automatically.
 
 ---
 
-### Track Clicks
-
-**✅ Automatic (Recommended)**
+## 🚨 CRITICAL: Impression Tracking Required (v0.9.0+)
 
-Clicks track automatically - no code needed! Just share the ad URL:
+**As of v0.9.0, impression tracking is REQUIRED to earn revenue from clicks.**
 
-```typescript
-const ad = await client.decideFromContext({ userMessage });
+When you show an ad to a user, you must track an impression. Clicks without prior impressions will:
+- ✅ Still redirect the user to the advertiser (good UX)
+- ❌ NOT charge the advertiser
+- ❌ NOT credit your earnings
 
-// Share this with users - clicks track automatically
-const link = ad.click_url;
+### Why This Matters
 
-// Works in: chat apps, email, SMS, web apps, anywhere
-```
+This prevents developers from filtering ads client-side and still earning revenue from clicks. It ensures clean data and accurate quality metrics for the advertising exchange.
 
-**📊 Optional: Track Impressions**
+### Using `decideFromContext()` (Recommended)
 
-Track when you *show* an ad (before user clicks):
+**Good news:** If you're using the SDK's `decideFromContext()` method, impressions are tracked **automatically**. No changes needed.
 
 ```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'
-  }
+// Impressions tracked automatically ✅
+const ad = await client.decideFromContext({
+  userMessage: "I need car insurance",
+  placement: 'sponsored_suggestion'
 });
+
+if (ad) {
+  // Show ad to user
+  displayAd(ad);
+}
 ```
 
-<details>
-<summary>Advanced: Manual click tracking (legacy)</summary>
+### Using Raw HTTP or `decide()` (Manual Tracking Required)
 
-If you need to track clicks manually (not recommended - auto-tracking is easier):
+If you're making raw HTTP calls or using the low-level `decide()` method, you **must manually track impressions**:
 
 ```typescript
-// Before redirecting to ad.click_url
-await client.trackClickFromAd(ad, {
-  click_context: "What you showed the user"
+// Step 1: Get ad
+const response = await fetch('https://peruwnbrqkvmrldhpoom.supabase.co/functions/v1/decide', {
+  method: 'POST',
+  headers: { 'X-AM-API-Key': 'am_live_...' },
+  body: JSON.stringify({ context: 'I need car insurance' })
 });
+const data = await response.json();
+
+if (data.status === 'filled') {
+  const ad = data.units[0];
+
+  // Step 2: Track impression IMMEDIATELY when showing ad ✅
+  await fetch('https://peruwnbrqkvmrldhpoom.supabase.co/functions/v1/event', {
+    method: 'POST',
+    headers: { 'X-AM-API-Key': 'am_live_...' },
+    body: JSON.stringify({
+      event_id: `evt_${crypto.randomUUID()}`,
+      event_type: 'impression',
+      occurred_at: new Date().toISOString(),
+      agent_id: 'YOUR_AGENT_ID',
+      unit_id: ad.unit_id,
+      tracking_token: ad.tracking.token
+    })
+  });
 
-// Then redirect: window.location.href = ad.click_url
+  // Step 3: Now safe to show ad and earn from clicks
+  displayAd(ad);
+}
 ```
 
-**Note:** Auto-tracking is simpler and works in more scenarios (email, SMS, etc).
-
-</details>
-
 ---
 
-## API Reference
+## Use Case 1: Monetize Your Chatbot or AI Assistant
 
-### Essential Functions
+Any app with conversations can earn revenue. Users ask questions with commercial intent every day — insurance, legal help, home services, travel, weddings, software. When they do, you can surface a relevant offer and earn.
 
-#### `new AttentionMarketClient(config)`
-Initialize the SDK with your API key and agent ID
+**Platforms this works on:**
 
-```typescript
-const client = new AttentionMarketClient({
-  apiKey: process.env.ATTENTIONMARKET_API_KEY,
-  agentId: 'your_agent_id'
-});
-```
+| Type | Examples |
+|------|---------|
+| **AI Assistants** | Mobile AI apps, productivity tools, personal assistants |
+| **Chatbots** | Website chat, customer service bots, FAQ bots |
+| **Messaging Bots** | WhatsApp, Discord, Telegram, Slack |
+| **Voice Assistants** | Alexa Skills, Google Actions, voice apps |
+| **AI Companions** | Coaching bots, tutors, entertainment assistants |
 
-#### `client.decideFromContext(params)`
-Get a contextually relevant ad based on user's message
+### How It Works
 
-```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
+User sends message → You call our API with context → We return a relevant ad
+→ You show it → User clicks → You earn $5–$150
 ```
 
-**No manual tracking code needed.** Works in chat apps, emails, SMS, anywhere.
+### Platform Examples
 
-#### `client.track(event)` (Optional)
-Track impressions or custom events
+**iOS (Swift)** — drop this into your Xcode project:
+```swift
+// Initialize once
+let client = AttentionMarketClient(
+    apiKey: "am_live_YOUR_KEY",
+    agentId: "agt_YOUR_ID"
+)
 
-```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
-});
+// Call after your AI responds
+if let ad = await client.getAd(for: userMessage) {
+    showAdInChat(
+        title: ad.suggestion.title,
+        body: ad.suggestion.body,
+        cta: ad.suggestion.cta,
+        url: ad.suggestion.trackingUrl
+    )
+}
 ```
+[Full iOS example →](./examples/ios/AttentionMarketClient.swift)
 
-### 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);
+**Android (Kotlin)**:
+```kotlin
+val client = AttentionMarketClient(
+    apiKey = "am_live_YOUR_KEY",
+    agentId = "agt_YOUR_ID"
+)
+
+client.getAd(context = userMessage)?.let { ad ->
+    showAdInChat(
+        title = ad.suggestion.title,
+        body = ad.suggestion.body,
+        url = ad.suggestion.trackingUrl
+    )
+}
 ```
+[Full Android example →](./examples/android/AttentionMarketClient.kt)
 
 ---
 
-## 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:
-
-```typescript
-import { AttentionMarketClient } from '@the_ro_show/agent-ads-sdk';
-
-const client = new AttentionMarketClient({
-  apiKey: process.env.ATTENTIONMARKET_API_KEY,
-  agentId: 'your_agent_id'
+**Web (JavaScript)** — plain fetch, no dependencies:
+```javascript
+const response = await fetch('https://peruwnbrqkvmrldhpoom.supabase.co/functions/v1/decide', {
+  method: 'POST',
+  headers: {
+    'X-AM-API-Key': 'am_live_YOUR_KEY',
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({ context: userMessage })
 });
 
-async function handleUserMessage(userMessage: string) {
-  const ad = await client.decideFromContext({ userMessage });
-
-  if (!ad) {
-    return null;  // No ads available
-  }
-
-  // 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);
-
-  // 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
-  });
+const data = await response.json();
 
-  return ad;
+if (data.status === 'filled') {
+  const ad = data.units[0];
+  showAdInChat(ad.suggestion.title, ad.suggestion.body, ad.suggestion.tracking_url);
 }
 ```
+[Full Web example →](./examples/web/attentionmarket.js)
 
 ---
 
-### Testing
-
-#### `MockAttentionMarketClient`
-
-Mock client for testing without API calls. Simulates latency and fill rate behavior.
-
-```typescript
-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%)
-  latencyMs: 100,    // Simulate API latency
-  verbose: true      // Log activity
-});
-
-// Works exactly like the real client
-const ad = await client.decideFromContext({ userMessage: "test" });
+**Node.js (optional SDK)**:
+```bash
+npm install @the_ro_show/agent-ads-sdk
 ```
+```javascript
+import { AttentionMarketClient } from '@the_ro_show/agent-ads-sdk';
 
----
-
-### Using Test vs Live Keys
-
-**Test Environment:**
-```typescript
 const client = new AttentionMarketClient({
-  apiKey: process.env.ATTENTIONMARKET_TEST_KEY  // am_test_...
+  apiKey: process.env.ATTENTIONMARKET_API_KEY,
+  agentId: process.env.ATTENTIONMARKET_AGENT_ID
 });
-```
 
-**Production Environment:**
-```typescript
-const client = new AttentionMarketClient({
-  apiKey: process.env.ATTENTIONMARKET_API_KEY  // am_live_...
-});
+const ad = await client.decideFromContext({ userMessage });
+if (ad) console.log(ad.creative.title, ad.click_url);
 ```
 
 ---
 
-### Security
-
-#### Server-Side Only
-
-**IMPORTANT:** This SDK must run server-side. Never expose your API key in client-side code.
+## Use Case 2: List Your AI Agent on the Exchange
 
-**✅ Supported:**
-- Node.js servers
-- Serverless functions (AWS Lambda, Vercel, Cloudflare Workers)
-- Server-side rendering (Next.js, Remix)
+You built a specialized AI agent — a legal document drafter, a wedding photographer booker, a travel planner, a code reviewer. Other AI assistants encounter users who need exactly what you do every day. List your agent on AttentionMarket and earn every time another agent calls yours.
 
-**❌ Not supported:**
-- Browser JavaScript
-- Client-side React/Vue/Angular
-- Mobile apps
+**This is the ad exchange for the agentic world.** Instead of humans clicking ads, AI agents discover and call specialized agents. You pay to be discovered. You earn when your agent gets used.
 
-#### 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`:
+### How It Works
 
 ```
-.env
-.env.local
+General assistant encounters a task it can't handle well
+→ Calls AttentionMarket with context + response_type: "agent"
+→ Exchange returns the best specialized agent for that task
+→ General assistant calls your agent
+→ You earn per call
 ```
 
-#### Sanitize Ad Content
+### Example
 
-Ad content comes from third-party advertisers. Always sanitize before rendering in HTML:
+**Developer A** built a general wedding planning AI assistant. A user asks: *"Can you find me a photographer in Austin under $3,000?"*
 
-```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>`;
+Developer A's assistant calls AttentionMarket:
+```bash
+curl -X POST https://peruwnbrqkvmrldhpoom.supabase.co/functions/v1/decide \
+  -H "X-AM-API-Key: am_live_DEV_A_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "context": "User needs a wedding photographer in Austin under $3,000",
+    "response_type": "agent"
+  }'
+```
+
+**AttentionMarket returns Developer B's agent:**
+```json
+{
+  "status": "filled",
+  "units": [{
+    "agent_name": "WeddingPhoto AI",
+    "capability": "Book wedding photographers by location and budget",
+    "endpoint": "https://weddingphoto.ai/api/v1",
+    "input_description": "Send: location (string), budget (number), date (string)",
+    "output_description": "Returns: photographer name, price, booking URL",
+    "tracking": {
+      "call_url": "https://.../track-call/token"
+    }
+  }]
 }
 ```
 
----
+**Developer A** calls WeddingPhoto AI, gets a result, passes it back to the user.
+**Developer B** earns per call. **Developer A** earns a routing fee.
 
-### Manual Category Targeting
+### List Your Agent
 
-#### `decide()` - Specify exact categories
+Sign up as an advertiser at [api.attentionmarket.ai](https://api.attentionmarket.ai) and create an **Agent Ad** campaign:
 
-When you know the exact category, use manual taxonomy matching for deterministic results.
+| Field | Description |
+|-------|-------------|
+| Agent Name | Display name (e.g. "WeddingPhoto AI") |
+| What does your agent do? | Natural language capability description — used for matching |
+| Endpoint URL | Where calling agents send requests |
+| What to send | Input format description |
+| What you return | Output format description |
+| Bid per call | What you pay each time your agent is called |
 
-```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' }
-  }
-});
-```
-
-See [TAXONOMY_SYSTEM.md](./TAXONOMY_SYSTEM.md) for all categories.
+**Matching is semantic** — describe your agent clearly in plain English and we handle the rest.
 
 ---
 
-### 🌐 Intenture Network APIs (Agent-to-Agent)
-
-#### `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.
+## Revenue Model
 
-```typescript
-const offer = await client.requestOffer({
-  placementId: 'order_card',
-  intentKey: 'coffee.purchase.delivery',
-  context: { geo: { city: 'SF', country: 'US' } }
-});
-```
+### As a Developer (showing ads or routing to agents)
 
-#### `requestOfferFromContext()` - Semantic discovery
+- **70% revenue share** on every click or agent call you facilitate
+- Earn $5–$150 per click for ads
+- Earn a routing fee per agent-to-agent call
+- Monthly payouts via Stripe (minimum $100 balance)
+- Free to integrate — no setup fees, no monthly costs
 
-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({
-  placementId: 'chat_suggestion',
-  userMessage: "I'm so tired, long day at work...",
-  conversationHistory: ["How was your day?", "Exhausting"],
-  context: { geo: { city: 'NYC' } }
-});
-```
+**Example earnings:**
 
-#### Revenue Share (Preview)
+| Monthly clicks/calls | Avg payout | Monthly revenue |
+|---------------------|------------|-----------------|
+| 50 | $50 | $2,500 |
+| 200 | $50 | $10,000 |
+| 1,000 | $50 | $50,000 |
 
-If another agent sends users to you, include their agent_id to split revenue (0-50%). Currently in preview mode - payouts activate Q2 2026.
+### As an Agent Advertiser (listing your agent)
 
-```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
-});
-```
+- Pay per click (Link Ad) or pay per call (Agent Ad)
+- Second-price auction — you bid a max, you often pay less
+- Full budget controls — set a cap, campaign pauses when spent
+- Track spend and performance in the advertiser dashboard
 
 ---
 
-### 🧠 Intent Detection
-
-#### `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'
-detectIntent("Compare car insurance options") // → 'compare'
-detectIntent("Get car insurance quote")       // → 'quote'
-detectIntent("I want to buy car insurance")   // → 'apply'
-```
-
-#### `buildTaxonomy()` - Type-safe taxonomy builder
-
-```typescript
-const taxonomy = buildTaxonomy('insurance', 'auto', 'full_coverage', 'quote');
-// → "insurance.auto.full_coverage.quote"
-```
-
-#### `suggestTaxonomies()` - Smart taxonomy recommendations
-
-```typescript
-const suggestions = suggestTaxonomies("I need a lawyer for divorce");
-// → ['legal.family.divorce.consultation', 'legal.family.custody.consultation']
-```
+## API Reference
 
-#### Taxonomy Utilities
-- `isValidTaxonomy(taxonomy)` - Validate taxonomy format
-- `parseTaxonomy(taxonomy)` - Parse into components
-- `getBaseTaxonomy(taxonomy)` - Get taxonomy without intent
-- `matchesTaxonomy(tax1, tax2)` - Check if taxonomies match
-- `getVertical(taxonomy)` - Extract industry vertical
+### `POST /v1/decide`
 
----
+**Base URL:** `https://peruwnbrqkvmrldhpoom.supabase.co/functions/v1/decide`
 
-### 🎨 Response Formatting
+**Required header:** `X-AM-API-Key: am_live_...` or `am_test_...`
 
-#### `formatNatural()` - Convert ads into natural conversation
+### Simple Request (recommended)
 
-```typescript
-const formatted = formatNatural(ad, {
-  tone: 'friendly',
-  includeDisclosure: true
-});
-// → "I found a great option for you! [Sponsored: Lemonade]..."
+```json
+{
+  "context": "I need car insurance"
+}
 ```
 
-#### `formatInlineMention()` - Subtle in-message placement
+### Simple Request with Optional Fields
 
-```typescript
-const mention = formatInlineMention(ad);
-// → "Btw, Lemonade offers 20% off for new drivers [Sponsored]"
+```json
+{
+  "context": "I need car insurance",
+  "country": "US",
+  "language": "en",
+  "platform": "ios"
+}
 ```
 
-#### `validateAdFits()` - Check if ad matches context
+### Request an Agent Instead of an Ad
 
-```typescript
-const fits = validateAdFits(ad, conversationContext);
-if (fits) {
-  // Show the ad
+```json
+{
+  "context": "User needs a wedding photographer in Austin",
+  "response_type": "agent"
 }
 ```
 
----
-
-### 📊 Event Tracking
-
-#### `trackImpression()` - Log when users see an ad
+### Advanced Request (full control)
 
-```typescript
-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
-});
+```json
+{
+  "request_id": "req_custom_123",
+  "agent_id": "agt_YOUR_ID",
+  "placement": "chat_inline",
+  "opportunity": {
+    "intent": { "taxonomy": "insurance.auto.quote" },
+    "context": { "country": "US", "language": "en", "platform": "ios" }
+  },
+  "context": "I need car insurance"
+}
 ```
 
----
-
-### 🛠️ Helper Utilities
-
-#### `createOpportunity()` - Build opportunity objects
-
-```typescript
-const opportunity = createOpportunity({
-  taxonomy: 'insurance.auto.quote',
-  country: 'US'
-});
+### Response: Ad Filled
+
+```json
+{
+  "request_id": "req_abc123",
+  "decision_id": "dec_xyz789",
+  "status": "filled",
+  "ttl_ms": 300000,
+  "units": [{
+    "unit_id": "unit_123",
+    "suggestion": {
+      "title": "Get 20% off car insurance",
+      "body": "Compare quotes in minutes",
+      "cta": "Get a Quote",
+      "tracking_url": "https://.../track-click/...",
+      "action_url": "https://progressive.com/quote"
+    },
+    "tracking": {
+      "token": "trk_abc",
+      "impression_url": "https://.../event",
+      "click_url": "https://.../click/trk_abc"
+    }
+  }]
+}
 ```
 
-#### Security Helpers
-- `escapeHTML(text)` - Sanitize ad content before rendering
-- `sanitizeURL(url)` - Validate and sanitize URLs
-
-#### ID Generation
-- `generateUUID()` - Create unique request IDs
-- `generateTimestamp()` - Generate API-compatible timestamps
-
----
-
-### ⚠️ Error Handling
-
-#### `APIRequestError` - API returned an error
-
-Thrown when the backend rejects your request. Includes detailed error message and request_id.
-
-#### `NetworkError` - Connection failed
-
-Network issues or backend unavailable. Includes automatic retry logic.
-
-#### `TimeoutError` - Request exceeded timeout
+### Response: No Fill
 
-Request took too long (default 5s). Configure with `timeoutMs` in constructor.
-
-```typescript
-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);
-  }
+```json
+{
+  "status": "no_fill",
+  "units": []
 }
 ```
 
-</details>
-
----
-
-## Monetize Your AI Agent
-
-Stop giving away your AI agent for free. Start earning revenue from every conversation.
+### Key Response Fields
 
-**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
+| Field | Use |
+|-------|-----|
+| `status` | `"filled"` or `"no_fill"` |
+| `suggestion.title` | Ad headline to show |
+| `suggestion.body` | Ad description to show |
+| `suggestion.cta` | Button text |
+| `suggestion.tracking_url` | **Send users here on click** — tracks automatically |
+| `suggestion.action_url` | Direct advertiser URL (display only, no tracking) |
 
-**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
+**Always use `tracking_url` for clicks.** This is how clicks are tracked and how you get paid.
 
-**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)
+### HTTP Status Codes
 
-**Integration time:** 10 minutes. Four functions. Production-ready.
+| Code | Meaning |
+|------|---------|
+| `200` | Success — check `status` field |
+| `400` | Bad request — missing `context` field |
+| `401` | Invalid API key |
+| `429` | Rate limit exceeded (1,000 req/min) — retry after 60s |
+| `500` | Server error — retry with backoff |
 
 ---
 
-## Examples
-
-**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
+## Testing
 
-**Testing** (~320 lines):
-- [test-with-mocks.ts](./examples/test-with-mocks.ts) - Test without API calls
+Use your test key (`am_test_...`) during development — same API, no real money moves.
 
-Run any example:
+**Validate your setup:**
 ```bash
-npx tsx examples/basic-example.ts
+node test-integration.js      # Tests connectivity and credentials
+node validate-production.js   # Full production readiness check (4/4 ✅)
 ```
 
----
-
-## For AI Agents
+Download: [test-integration.js](./test-integration.js) | [validate-production.js](./validate-production.js)
 
-**AI agents:** Read **[AI_AGENT_SETUP_GUIDE.md](./AI_AGENT_SETUP_GUIDE.md)** for complete step-by-step integration instructions.
+---
 
-**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"
+## Get Started
 
-The agent will handle: getting credentials, installing SDK, writing integration code, testing, and deployment setup.
+1. **Sign up** at [api.attentionmarket.ai](https://api.attentionmarket.ai) — get your test key, live key, and agent ID
+2. **Test it** — run the curl above with your test key
+3. **Integrate** — add 5 lines to your existing chatbot or assistant
+4. **Go live** — swap test key for live key, start earning
 
 ---
 
 ## Support
 
+- **Dashboard:** [api.attentionmarket.ai](https://api.attentionmarket.ai)
 - **Issues:** [GitHub Issues](https://github.com/rtrivedi/agent-ads-sdk/issues)
-- **Email:** support@attentionmarket.com
+- **Email:** support@attentionmarket.ai
 
 ---
 
 ## License
 
-MIT
+MIT — see [LICENSE](./LICENSE)