@the_ro_show/agent-ads-sdk 0.6.0 → 0.9.0

package/README.md

@@ -1,611 +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. Similar to AdSense but designed for conversational interfaces. It's time to start monetizing your AI agents!
+**The ad exchange for the AI era. Monetize your chatbot, AI assistant, or AI agent with one API call.**
 
-- **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
+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 [attentionmarket.com/signup](https://api.attentionmarket.ai/) to receive:
-- Test key: `am_test_...`
-- Live key: `am_live_...`
-- Agent ID
+### 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.
 
-### 2. Install
-
-```bash
-npm install @the_ro_show/agent-ads-sdk
-```
+---
 
-### 3. Basic Usage
+## Quick Start — 30 Seconds
 
-```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 your API keys at [api.attentionmarket.ai](https://api.attentionmarket.ai), then:
 
-// Request an ad based on user message
-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"}'
+```
 
-if (ad) {
-  console.log(ad.creative.title);
-  console.log(ad.creative.body);
-  console.log(ad.creative.cta);
+**Response:**
+```json
+{
+  "status": "filled",
+  "units": [{
+    "suggestion": {
+      "title": "Get 20% off car insurance",
+      "body": "Compare quotes in minutes",
+      "cta": "Get a Quote",
+      "tracking_url": "https://..."
+    }
+  }]
 }
 ```
 
----
-
-## 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
-
-The API handles intent detection and ad matching automatically.
+Show `suggestion.title` and `suggestion.body` to your user. When they click, send them to `tracking_url`. That's it — you get paid automatically.
 
 ---
 
-## Complete Example
+## 🚨 CRITICAL: Impression Tracking Required (v0.9.0+)
 
-Full integration including ad retrieval, display, and click tracking:
+**As of v0.9.0, impression tracking is REQUIRED to earn revenue from clicks.**
 
-```typescript
-import { AttentionMarketClient } from '@the_ro_show/agent-ads-sdk';
-
-const client = new AttentionMarketClient({
-  apiKey: process.env.ATTENTIONMARKET_API_KEY,
-  agentId: 'your_agent_id'
-});
-
-async function handleUserMessage(userMessage: string) {
-  const ad = await client.decideFromContext({ userMessage });
-
-  if (!ad) {
-    return null;  // No ads available
-  }
-
-  // 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);
-
-  // 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
-  });
-
-  return ad;
-}
-```
+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
 
----
-
-## API Reference
+### Why This Matters
 
-### Primary API
+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.
 
-#### `decideFromContext(params)` → `Promise <OfferResponse | null>`
+### Using `decideFromContext()` (Recommended)
 
-Pass a user message and optionally conversation history. Returns a matching ad or null if no fill.
+**Good news:** If you're using the SDK's `decideFromContext()` method, impressions are tracked **automatically**. No changes needed.
 
 ```typescript
+// Impressions tracked automatically ✅
 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
+  userMessage: "I need car insurance",
+  placement: 'sponsored_suggestion'
 });
-```
-
-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
 
-### Revenue Tracking
-
-#### `trackClick(params)` → `Promise<void>`
-
-Records user clicks for revenue attribution. Call this when a user clicks an ad. Handles deduplication and retries automatically.
-
-**Required:** `click_context` - The actual message shown to the user. This helps optimize ad creative based on what converts.
-
-```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"
-});
+if (ad) {
+  // Show ad to user
+  displayAd(ad);
+}
 ```
 
-### Testing
+### Using Raw HTTP or `decide()` (Manual Tracking Required)
 
-#### `MockAttentionMarketClient`
-
-Mock client for testing without API calls. Simulates latency and fill rate behavior.
+If you're making raw HTTP calls or using the low-level `decide()` method, you **must manually track impressions**:
 
 ```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% of time)
-  latencyMs: 100,    // Simulate API latency
-  verbose: true      // Log what's happening
+// 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
+    })
+  });
 
-// Works exactly like the real client
-const ad = await client.decideFromContext({ userMessage: "test" });
+  // Step 3: Now safe to show ad and earn from clicks
+  displayAd(ad);
+}
 ```
 
 ---
 
-## Advanced Features
-
-<details>
-<summary><strong>Click to view advanced APIs (most developers don't need these)</strong></summary>
+## Use Case 1: Monetize Your Chatbot or AI Assistant
 
-<br>
+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.
 
-The simple `decideFromContext()` API handles everything for 90% of use cases. But if you need more control:
+**Platforms this works on:**
 
-### Manual Category Targeting
+| 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 |
 
-#### `decide()` - Specify exact categories
-When you know the exact category, use manual taxonomy matching for deterministic results.
+### How It Works
 
-```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.
-
----
-
-### 🌐 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
-const offer = await client.requestOffer({
-  placementId: 'order_card',
-  intentKey: 'coffee.purchase.delivery',
-  context: { geo: { city: 'SF', country: 'US' } }
-});
+User sends message → You call our API with context → We return a relevant ad
+→ You show it → User clicks → You earn $5–$150
 ```
 
-#### `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' } }
-});
+### Platform Examples
+
+**iOS (Swift)** — drop this into your Xcode project:
+```swift
+// Initialize once
+let client = AttentionMarketClient(
+    apiKey: "am_live_YOUR_KEY",
+    agentId: "agt_YOUR_ID"
+)
+
+// 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)
 
-#### 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.
+---
 
-```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
-});
+**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)
 
 ---
 
-### 🧠 Intent Detection
+**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 })
+});
 
-#### `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'.
+const data = await response.json();
 
-```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'
+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)
 
-#### `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');
-// → "insurance.auto.full_coverage.quote"
+**Node.js (optional SDK)**:
+```bash
+npm install @the_ro_show/agent-ads-sdk
 ```
+```javascript
+import { AttentionMarketClient } from '@the_ro_show/agent-ads-sdk';
 
-#### `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.
+const client = new AttentionMarketClient({
+  apiKey: process.env.ATTENTIONMARKET_API_KEY,
+  agentId: process.env.ATTENTIONMARKET_AGENT_ID
+});
 
-```typescript
-const suggestions = suggestTaxonomies("I need a lawyer for divorce");
-// → ['legal.family.divorce.consultation', 'legal.family.custody.consultation']
+const ad = await client.decideFromContext({ userMessage });
+if (ad) console.log(ad.creative.title, ad.click_url);
 ```
 
-#### 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
-
 ---
 
-### 🎨 Response Formatting
+## Use Case 2: List Your AI Agent on the Exchange
 
-#### `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.
+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.
 
-```typescript
-const formatted = formatNatural(ad, {
-  tone: 'friendly',
-  includeDisclosure: true
-});
-// → "I found a great option for you! [Sponsored: Lemonade]..."
-```
+**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.
 
-#### `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.
+### How It Works
 
-```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.
-
-```typescript
-const fits = validateAdFits(ad, conversationContext);
-if (fits) {
-  // Show the ad
-}
+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
 ```
 
----
-
-### 📊 Event Tracking
+### Example
 
-#### `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.
+**Developer A** built a general wedding planning AI assistant. A user asks: *"Can you find me a photographer in Austin under $3,000?"*
 
-```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
-});
+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"
+  }'
 ```
 
-#### `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'
-});
+**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.
 
-### 🛠️ Helper Utilities
+### List Your Agent
 
-#### `createOpportunity()` - Build opportunity objects easily
-Helper to construct the opportunity payload for decide() calls. Handles defaults and validation.
+Sign up as an advertiser at [api.attentionmarket.ai](https://api.attentionmarket.ai) and create an **Agent Ad** campaign:
 
-```typescript
-const opportunity = createOpportunity({
-  taxonomy: 'insurance.auto.quote',
-  country: 'US'
-});
-```
+| 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 |
 
-#### Security Helpers
-- `escapeHTML(text)` - Sanitize ad content before rendering to prevent XSS attacks
-- `sanitizeURL(url)` - Validate and sanitize URLs before opening
+**Matching is semantic** — describe your agent clearly in plain English and we handle the rest.
 
-**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
+## Revenue Model
 
----
+### As a Developer (showing ads or routing to agents)
 
-### 🧪 Testing
+- **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
 
-#### `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.
+**Example earnings:**
 
-```typescript
-import { MockAttentionMarketClient } from '@the_ro_show/agent-ads-sdk';
+| Monthly clicks/calls | Avg payout | Monthly revenue |
+|---------------------|------------|-----------------|
+| 50 | $50 | $2,500 |
+| 200 | $50 | $10,000 |
+| 1,000 | $50 | $50,000 |
 
-const client = new MockAttentionMarketClient({
-  fillRate: 1.0,     // Always return ads
-  latencyMs: 100,    // Simulate API latency
-  verbose: true      // Log activity
-});
+### As an Agent Advertiser (listing your agent)
 
-// Works exactly like real client, but returns mock data
-const decision = await client.decide(request);
-```
+- 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
 
 ---
 
-### ⚠️ Error Handling
+## API Reference
+
+### `POST /v1/decide`
 
-#### `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.
+**Base URL:** `https://peruwnbrqkvmrldhpoom.supabase.co/functions/v1/decide`
 
-#### `NetworkError` - Connection failed
-Network issues, DNS failures, or backend unavailable. Includes automatic retry logic for transient failures.
+**Required header:** `X-AM-API-Key: am_live_...` or `am_test_...`
 
-#### `TimeoutError` - Request exceeded timeout
-Request took too long (default 5s). Configure with `timeoutMs` in constructor.
+### Simple Request (recommended)
 
-```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
+{
+  "context": "I need car insurance"
 }
 ```
 
-</details>
+### Simple Request with Optional Fields
 
----
+```json
+{
+  "context": "I need car insurance",
+  "country": "US",
+  "language": "en",
+  "platform": "ios"
+}
+```
 
-## Using Test vs Live Keys
+### Request an Agent Instead of an Ad
 
-### Test Environment
-Use your test key for development:
-```typescript
-const client = new AttentionMarketClient({
-  apiKey: process.env.ATTENTIONMARKET_TEST_KEY  // am_test_...
-});
+```json
+{
+  "context": "User needs a wedding photographer in Austin",
+  "response_type": "agent"
+}
 ```
 
-### Production Environment
-Use your live key for production:
-```typescript
-const client = new AttentionMarketClient({
-  apiKey: process.env.ATTENTIONMARKET_API_KEY  // am_live_...
-});
+### Advanced Request (full control)
+
+```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"
+}
 ```
 
----
-
-## Sanitizing Ad Content
-
-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.creative.title);
-const safeURL = sanitizeURL(ad.click_url);
-
-if (safeURL) {
-  element.innerHTML = `<a href="${safeURL}">${safeTitle}</a>`;
+### 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"
+    }
+  }]
 }
 ```
 
-<details>
-<summary><strong>Security considerations</strong></summary>
+### Response: No Fill
 
-<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.
+```json
+{
+  "status": "no_fill",
+  "units": []
+}
+```
 
-**Supported:**
-- Node.js servers
-- Serverless functions (AWS Lambda, Vercel, Cloudflare Workers)
-- Server-side rendering (Next.js, Remix)
+### Key Response Fields
 
-**Not supported:**
-- Browser JavaScript
-- Client-side React/Vue/Angular
-- Mobile apps
+| 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) |
 
-### Additional Guidelines
+**Always use `tracking_url` for clicks.** This is how clicks are tracked and how you get paid.
 
-See [SECURITY.md](./SECURITY.md) for complete security best practices.
+### HTTP Status Codes
 
-</details>
+| 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
-
-**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)
+## Testing
 
-**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)
+Use your test key (`am_test_...`) during development — same API, no real money moves.
 
-Run any example:
+**Validate your setup:**
 ```bash
-npx tsx examples/claude-tool-use-minimal.ts
+node test-integration.js      # Tests connectivity and credentials
+node validate-production.js   # Full production readiness check (4/4 ✅)
 ```
 
----
-
-## 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)
+Download: [test-integration.js](./test-integration.js) | [validate-production.js](./validate-production.js)
 
 ---
 
-## 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.
+## Get Started
 
-<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>
+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)
-- **Docs:** [SIMPLE_INTEGRATION_GUIDE.md](./SIMPLE_INTEGRATION_GUIDE.md)
-- **Email:** support@attentionmarket.com
+- **Email:** support@attentionmarket.ai
 
 ---
 
 ## License
 
-MIT
-
----
-
-## Changelog
-
-See [CHANGELOG.md](./CHANGELOG.md) for detailed version history.
+MIT — see [LICENSE](./LICENSE)