@the_ro_show/agent-ads-sdk 0.10.0 → 0.13.0

package/README.md

@@ -315,31 +315,37 @@ Sign up as an advertiser at [api.attentionmarket.ai](https://api.attentionmarket
 
 ---
 
-## 💰 Earn Bonuses with Feedback (v0.10.0+)
+## 💰 Earn Bonuses with Feedback (v0.11.0+)
 
-Send feedback on ad performance to earn **conversion-validated bonuses**.
+Send feedback on ad performance to earn **AI-validated conversion bonuses**.
 
 ### How It Works
 
 1. **Show an ad** to your user (impression tracked automatically in v0.9.0+)
 2. **User clicks** → You earn base click revenue
-3. **Send your prediction** about user sentiment:
-   - `positive` - You think user will convert
-   - `neutral` - No strong signal
-   - `negative` - User didn't like it
+3. **Send user's actual response** → AI analyzes sentiment automatically
 4. **Wait 7 days** → System checks if user actually converted
-5. **Get bonus or penalty:**
+5. **Get bonus or penalty based on AI prediction:**
    - ✅ Correct positive prediction → **+15% bonus**
    - ❌ Wrong positive prediction → **-5% penalty**
    - 🤷 Neutral/negative → no bonus/penalty (data only)
 
+### What's New in v0.11.0
+
+**Backend now analyzes sentiment for you using AI:**
+- You just send the user's actual response text
+- No need to classify sentiment yourself
+- More consistent quality scores across all developers
+- Harder to game (can't spam "positive" on everything)
+
 ### Anti-Fraud Design
 
-**Why penalties?** To prevent developers from spamming "positive" on every click.
+**Why penalties?** To prevent developers from gaming the system.
 
-- Spamming = net loss (most clicks don't convert)
+- AI analyzes actual user responses (not developer claims)
+- Spamming fake positive responses = net loss
 - Accuracy = net gain (bonus > penalty when right)
-- System rewards honest, confident predictions
+- System rewards honest data collection
 
 ### Usage Example
 
@@ -356,14 +362,17 @@ const ad = await client.decideFromContext({
 });
 
 if (ad) {
-  // User clicks and seems very interested
+  // User responds after clicking
+  const userResponse = "This looks perfect! How do I sign up?";
+
   await client.sendFeedback({
     tracking_token: ad.tracking_token,
-    reaction: 'positive',
-    context: 'User asked follow-up questions about coverage'
+    user_response: userResponse,
+    agent_response: "Here's the signup link...",
+    additional_context: "User spent 2 minutes on offer page"
   });
 
-  // Potential bonus: +15% if they convert in 7 days
+  // AI will detect positive sentiment → +15% bonus if user converts
 }
 ```
 
@@ -375,8 +384,9 @@ curl -X POST https://peruwnbrqkvmrldhpoom.supabase.co/functions/v1/feedback \
   -H "Content-Type: application/json" \
   -d '{
     "tracking_token": "eyJhbGc...",
-    "reaction": "positive",
-    "context": "User loved the recommendation"
+    "user_response": "This looks great! How do I get started?",
+    "agent_response": "Here is the signup process...",
+    "additional_context": "User asked 3 follow-up questions"
   }'
 ```
 
@@ -384,28 +394,174 @@ curl -X POST https://peruwnbrqkvmrldhpoom.supabase.co/functions/v1/feedback \
 ```json
 {
   "success": true,
-  "prediction_recorded": "positive",
+  "sentiment_detected": "positive",
   "potential_bonus": "$1.05",
-  "message": "Feedback recorded! If your prediction is correct (user converts within 7 days), you'll earn a +15% bonus. Wrong predictions incur a -5% penalty.",
+  "potential_penalty": "$0.35",
+  "message": "Feedback recorded! Detected sentiment: positive. If correct (user converts within 7 days), you'll earn a +15% bonus. Wrong predictions incur a -5% penalty.",
   "resolution_date": "2026-02-28T12:00:00Z"
 }
 ```
 
 ### When To Send Feedback
 
-**Good times to send positive:**
-- User explicitly asked "how do I sign up?"
-- User clicked and spent >30 seconds on page
-- User added item to cart
-- User asked follow-up questions
+**Good signals to capture:**
+- User's actual text responses after clicking
+- Your agent's follow-up messages
+- Context about how long user engaged with the offer
+- Any follow-up questions or actions
 
-**Don't spam:**
-- Only send when you have real signal
-- Wrong predictions cost you money
+**Best practices:**
+- Send actual user text, not summaries
+- Include your agent's response for context
+- Only send when you have meaningful interaction data
 - Quality > quantity
 
 ---
 
+## 🎛️ Developer Controls (v0.12.0+)
+
+Take control of what ads appear in your app with quality, category, and advertiser filters.
+
+### Quality Score Filter
+
+Only show ads that meet your quality standards:
+
+```typescript
+const ad = await client.decideFromContext({
+  userMessage: "I need car insurance",
+  minQualityScore: 0.8  // Only ads with 0.8+ quality
+});
+```
+
+**Use cases:**
+- **Premium apps**: Set 0.9+ for best-in-class ads only
+- **General apps**: Set 0.7+ for good balance
+- **High-volume apps**: Set 0.5+ to maximize fill rate
+
+### Category Controls (IAB Taxonomy 3.0)
+
+Filter ads using **IAB Content Taxonomy 3.0** - the industry-standard category system used by Google Ads, Microsoft Ads, and all major ad platforms.
+
+**704 categories** across 38 top-level categories with 4-tier hierarchy.
+
+#### Discover Available Categories
+
+```typescript
+// Get all 38 top-level categories
+const tier1 = await client.getCategories({ tier: 1 });
+tier1.categories.forEach(cat => {
+  console.log(`${cat.id}: ${cat.name}`);
+});
+// Output: 1: Automotive, 31: Insurance, 150: Attractions, etc.
+
+// Get all subcategories of "Automotive" (ID: 1)
+const automotive = await client.getCategories({ parent_id: 1 });
+// Returns: Auto Insurance (31), Auto Repair (34), Auto Buying (30), etc.
+
+// Search for insurance-related categories
+const insurance = await client.getCategories({ search: 'insurance' });
+insurance.categories.forEach(cat => {
+  console.log(cat.full_path);
+});
+// Output: "Automotive > Auto Insurance", "Personal Finance > Insurance", etc.
+```
+
+#### Filter by Category
+
+Use IAB category IDs for precise control:
+
+```typescript
+// Insurance app: Only show insurance ads (by IAB ID)
+const ad = await client.decideFromContext({
+  userMessage: "I need car insurance",
+  allowedCategories: [31]  // 31 = Auto Insurance
+});
+
+// Block entire "Sensitive Topics" tree (IAB ID: 601)
+// This blocks all gambling, adult content, controversial topics, etc.
+const ad = await client.decideFromContext({
+  userMessage: "Help me with something",
+  blockedCategories: [601]  // Blocks parent + all children
+});
+
+// Wedding planner: Allow wedding + photography + food
+const ad = await client.decideFromContext({
+  userMessage: "Help me plan my wedding",
+  allowedCategories: [
+    603,  // Weddings (Personal Celebrations)
+    162,  // Photography (Hobbies & Interests)
+    190   // Restaurants (Food & Drink)
+  ]
+});
+```
+
+**Parent-Child Relationships:**
+- Blocking a parent category blocks ALL child categories automatically
+- Example: Blocking `1` (Automotive) blocks Auto Insurance, Auto Repair, etc.
+- Great for compliance: Block `601` (Sensitive Topics) to block gambling, adult, controversial in one go
+
+**Note:** If `allowedCategories` is set, `blockedCategories` is ignored.
+
+### Advertiser Blocklist
+
+Block specific advertisers based on user feedback:
+
+```typescript
+const ad = await client.decideFromContext({
+  userMessage: "I need legal help",
+  blockedAdvertisers: ['adv_abc123', 'adv_xyz789']
+});
+```
+
+Get advertiser IDs from previous ad responses.
+
+### Combined Controls
+
+Mix and match for precise control:
+
+```typescript
+const ad = await client.decideFromContext({
+  userMessage: "I need car insurance",
+  minQualityScore: 0.8,           // High quality only
+  blockedCategories: ['crypto'],   // No crypto ads
+  allowedCategories: ['insurance', 'finance']  // Relevant only
+});
+```
+
+### HTTP Example
+
+```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",
+    "minQualityScore": 0.8,
+    "blockedCategories": ["crypto", "gambling"]
+  }'
+```
+
+### Best Practices
+
+**Quality Scores:**
+- Start with no filter, monitor what you get
+- Gradually increase threshold if quality is lacking
+- Higher thresholds = fewer ads but better quality
+
+**Categories (IAB Taxonomy):**
+- Use `getCategories()` to discover the full 704-category taxonomy
+- Use `allowedCategories` for specialized apps (wedding planner = `[603]`, legal assistant = `[318]`)
+- Use `blockedCategories` for compliance (kids apps = block `[601]` Sensitive Topics)
+- Parent categories block all children automatically (block `[1]` Automotive = blocks all 40+ auto subcategories)
+- Full taxonomy reference: https://github.com/InteractiveAdvertisingBureau/Taxonomies
+
+**Advertiser Blocking:**
+- Collect user feedback on specific ads
+- Block advertisers with multiple complaints
+- Use sparingly - too many blocks reduce fill rate
+
+---
+
 ## API Reference
 
 ### `POST /v1/decide`

package/dist/index.d.mts

@@ -63,6 +63,39 @@ interface DecideFromContextRequest {
     language?: string;
     /** User's platform. Default: 'web' */
     platform?: 'web' | 'ios' | 'android' | 'desktop' | 'voice' | 'other';
+    /**
+     * Minimum quality score threshold (0.0 - 1.0).
+     * Only return ads with quality scores at or above this value.
+     * Higher values = better quality but lower fill rate.
+     *
+     * @example
+     * minQualityScore: 0.8  // Only show ads with 0.8+ quality
+     */
+    minQualityScore?: number;
+    /**
+     * Only show ads from these categories.
+     * If set, blockedCategories is ignored.
+     *
+     * @example
+     * allowedCategories: ['wedding', 'photography', 'venues']
+     */
+    allowedCategories?: string[];
+    /**
+     * Never show ads from these categories.
+     * Ignored if allowedCategories is set.
+     *
+     * @example
+     * blockedCategories: ['gambling', 'crypto', 'dating']
+     */
+    blockedCategories?: string[];
+    /**
+     * Never show ads from these advertisers.
+     * Use advertiser IDs from previous ad responses.
+     *
+     * @example
+     * blockedAdvertisers: ['adv_abc123', 'adv_xyz789']
+     */
+    blockedAdvertisers?: string[];
 }
 interface DecideResponse {
     request_id: string;
@@ -176,16 +209,19 @@ interface EventIngestResponse {
     accepted: boolean;
 }
 /**
- * Feedback reaction types for conversion-validated bonuses.
+ * Sentiment types detected by backend AI analysis.
  *
- * - positive: Predict user will convert (earn +15% if correct, -5% if wrong)
- * - neutral: No prediction (no bonus/penalty, data collection only)
- * - negative: User disliked the ad (no penalty, data collection only)
+ * - positive: User is interested/engaged (earn +15% if converts, -5% if not)
+ * - neutral: User is indifferent (no bonus/penalty, data only)
+ * - negative: User disliked the ad (no penalty, data only)
  */
-type FeedbackReaction = 'positive' | 'neutral' | 'negative';
+type FeedbackSentiment = 'positive' | 'neutral' | 'negative';
 /**
  * Send feedback on an ad after showing it to a user.
  *
+ * **New in v0.11.0:** Backend analyzes sentiment automatically using AI.
+ * Just send the user's actual response text - no need to classify it yourself.
+ *
  * **Anti-Fraud:** Bonuses are deferred and validated against actual conversions.
  * - Correct positive prediction → +15% bonus after 7 days
  * - Wrong positive prediction → -5% penalty after 7 days
@@ -195,18 +231,21 @@ type FeedbackReaction = 'positive' | 'neutral' | 'negative';
  * ```typescript
  * await client.sendFeedback({
  *   tracking_token: ad.tracking_token,
- *   reaction: 'positive',
- *   context: 'User loved the product recommendation!'
+ *   user_response: "This looks perfect! How do I sign up?",
+ *   agent_response: "Here's the signup link...",
+ *   additional_context: "User spent 2 minutes reading the offer"
  * });
  * ```
  */
 interface FeedbackRequest {
     /** Tracking token from the ad you showed */
     tracking_token: string;
-    /** Your prediction about user sentiment/conversion */
-    reaction: FeedbackReaction;
-    /** Optional context explaining why you think this (helps with quality scores) */
-    context?: string;
+    /** User's actual response text (required) */
+    user_response: string;
+    /** Your agent's response (optional, helps sentiment analysis) */
+    agent_response?: string;
+    /** Additional context about the interaction (optional) */
+    additional_context?: string;
 }
 /**
  * Response from sending feedback.
@@ -217,10 +256,12 @@ interface FeedbackRequest {
 interface FeedbackResponse {
     /** Whether feedback was recorded successfully */
     success: boolean;
-    /** What prediction was recorded */
-    prediction_recorded: FeedbackReaction;
+    /** AI-detected sentiment from user response */
+    sentiment_detected: FeedbackSentiment;
     /** Potential bonus if prediction is correct (not guaranteed) */
     potential_bonus: string;
+    /** Potential penalty if prediction is wrong */
+    potential_penalty: string;
     /** Explanation of the deferred bonus system */
     message: string;
     /** When the bonus will be resolved (7 days from now) */
@@ -549,6 +590,44 @@ interface GetServiceRequest {
         region?: string;
     };
 }
+interface IABCategory {
+    /** Unique IAB category ID */
+    id: number;
+    /** Parent category ID (null for tier 1 categories) */
+    parent_id: number | null;
+    /** Category name */
+    name: string;
+    /** Tier 1 category (top level) */
+    tier_1: string | null;
+    /** Tier 2 category (sub-category) */
+    tier_2: string | null;
+    /** Tier 3 category (sub-sub-category) */
+    tier_3: string | null;
+    /** Tier 4 category (deepest level) */
+    tier_4: string | null;
+    /** Full hierarchical path (e.g., "Automotive > Auto Insurance") */
+    full_path: string;
+}
+interface CategoryTaxonomyResponse {
+    /** Taxonomy version */
+    version: string;
+    /** Source organization */
+    source: string;
+    /** Reference URL */
+    url: string;
+    /** Total number of categories returned (after filtering) */
+    total: number;
+    /** Array of categories */
+    categories: IABCategory[];
+}
+interface GetCategoriesParams {
+    /** Filter by tier level (1-4) */
+    tier?: 1 | 2 | 3 | 4;
+    /** Filter by parent category ID */
+    parent_id?: number;
+    /** Search by name or path (case-insensitive) */
+    search?: string;
+}
 
 /**
  * Utility functions for the AttentionMarket SDK.
@@ -981,6 +1060,39 @@ declare class AttentionMarketClient {
      * ```
      */
     logServiceResult(params: ServiceResultRequest): Promise<ServiceResultResponse>;
+    /**
+     * Get IAB Content Taxonomy categories.
+     *
+     * Returns the complete IAB Content Taxonomy 3.0 (704 categories across 38 top-level categories).
+     * Supports filtering by tier level, parent category, or search term.
+     *
+     * Use this to discover available categories for `allowedCategories` and `blockedCategories` parameters.
+     *
+     * @param params - Optional filters (tier, parent_id, search)
+     * @returns The IAB Content Taxonomy with categories
+     *
+     * @example Get all Tier 1 categories (38 top-level categories)
+     * ```typescript
+     * const tier1 = await client.getCategories({ tier: 1 });
+     * console.log(`${tier1.total} top-level categories`);
+     * tier1.categories.forEach(cat => console.log(`${cat.id}: ${cat.name}`));
+     * ```
+     *
+     * @example Get all subcategories of "Automotive" (ID: 1)
+     * ```typescript
+     * const automotiveCategories = await client.getCategories({ parent_id: 1 });
+     * console.log(`Found ${automotiveCategories.total} automotive subcategories`);
+     * ```
+     *
+     * @example Search for insurance-related categories
+     * ```typescript
+     * const insuranceCategories = await client.getCategories({ search: 'insurance' });
+     * insuranceCategories.categories.forEach(cat => {
+     *   console.log(`${cat.id}: ${cat.full_path}`);
+     * });
+     * ```
+     */
+    getCategories(params?: GetCategoriesParams): Promise<CategoryTaxonomyResponse>;
 }
 
 /**

package/dist/index.d.ts

@@ -63,6 +63,39 @@ interface DecideFromContextRequest {
     language?: string;
     /** User's platform. Default: 'web' */
     platform?: 'web' | 'ios' | 'android' | 'desktop' | 'voice' | 'other';
+    /**
+     * Minimum quality score threshold (0.0 - 1.0).
+     * Only return ads with quality scores at or above this value.
+     * Higher values = better quality but lower fill rate.
+     *
+     * @example
+     * minQualityScore: 0.8  // Only show ads with 0.8+ quality
+     */
+    minQualityScore?: number;
+    /**
+     * Only show ads from these categories.
+     * If set, blockedCategories is ignored.
+     *
+     * @example
+     * allowedCategories: ['wedding', 'photography', 'venues']
+     */
+    allowedCategories?: string[];
+    /**
+     * Never show ads from these categories.
+     * Ignored if allowedCategories is set.
+     *
+     * @example
+     * blockedCategories: ['gambling', 'crypto', 'dating']
+     */
+    blockedCategories?: string[];
+    /**
+     * Never show ads from these advertisers.
+     * Use advertiser IDs from previous ad responses.
+     *
+     * @example
+     * blockedAdvertisers: ['adv_abc123', 'adv_xyz789']
+     */
+    blockedAdvertisers?: string[];
 }
 interface DecideResponse {
     request_id: string;
@@ -176,16 +209,19 @@ interface EventIngestResponse {
     accepted: boolean;
 }
 /**
- * Feedback reaction types for conversion-validated bonuses.
+ * Sentiment types detected by backend AI analysis.
  *
- * - positive: Predict user will convert (earn +15% if correct, -5% if wrong)
- * - neutral: No prediction (no bonus/penalty, data collection only)
- * - negative: User disliked the ad (no penalty, data collection only)
+ * - positive: User is interested/engaged (earn +15% if converts, -5% if not)
+ * - neutral: User is indifferent (no bonus/penalty, data only)
+ * - negative: User disliked the ad (no penalty, data only)
  */
-type FeedbackReaction = 'positive' | 'neutral' | 'negative';
+type FeedbackSentiment = 'positive' | 'neutral' | 'negative';
 /**
  * Send feedback on an ad after showing it to a user.
  *
+ * **New in v0.11.0:** Backend analyzes sentiment automatically using AI.
+ * Just send the user's actual response text - no need to classify it yourself.
+ *
  * **Anti-Fraud:** Bonuses are deferred and validated against actual conversions.
  * - Correct positive prediction → +15% bonus after 7 days
  * - Wrong positive prediction → -5% penalty after 7 days
@@ -195,18 +231,21 @@ type FeedbackReaction = 'positive' | 'neutral' | 'negative';
  * ```typescript
  * await client.sendFeedback({
  *   tracking_token: ad.tracking_token,
- *   reaction: 'positive',
- *   context: 'User loved the product recommendation!'
+ *   user_response: "This looks perfect! How do I sign up?",
+ *   agent_response: "Here's the signup link...",
+ *   additional_context: "User spent 2 minutes reading the offer"
  * });
  * ```
  */
 interface FeedbackRequest {
     /** Tracking token from the ad you showed */
     tracking_token: string;
-    /** Your prediction about user sentiment/conversion */
-    reaction: FeedbackReaction;
-    /** Optional context explaining why you think this (helps with quality scores) */
-    context?: string;
+    /** User's actual response text (required) */
+    user_response: string;
+    /** Your agent's response (optional, helps sentiment analysis) */
+    agent_response?: string;
+    /** Additional context about the interaction (optional) */
+    additional_context?: string;
 }
 /**
  * Response from sending feedback.
@@ -217,10 +256,12 @@ interface FeedbackRequest {
 interface FeedbackResponse {
     /** Whether feedback was recorded successfully */
     success: boolean;
-    /** What prediction was recorded */
-    prediction_recorded: FeedbackReaction;
+    /** AI-detected sentiment from user response */
+    sentiment_detected: FeedbackSentiment;
     /** Potential bonus if prediction is correct (not guaranteed) */
     potential_bonus: string;
+    /** Potential penalty if prediction is wrong */
+    potential_penalty: string;
     /** Explanation of the deferred bonus system */
     message: string;
     /** When the bonus will be resolved (7 days from now) */
@@ -549,6 +590,44 @@ interface GetServiceRequest {
         region?: string;
     };
 }
+interface IABCategory {
+    /** Unique IAB category ID */
+    id: number;
+    /** Parent category ID (null for tier 1 categories) */
+    parent_id: number | null;
+    /** Category name */
+    name: string;
+    /** Tier 1 category (top level) */
+    tier_1: string | null;
+    /** Tier 2 category (sub-category) */
+    tier_2: string | null;
+    /** Tier 3 category (sub-sub-category) */
+    tier_3: string | null;
+    /** Tier 4 category (deepest level) */
+    tier_4: string | null;
+    /** Full hierarchical path (e.g., "Automotive > Auto Insurance") */
+    full_path: string;
+}
+interface CategoryTaxonomyResponse {
+    /** Taxonomy version */
+    version: string;
+    /** Source organization */
+    source: string;
+    /** Reference URL */
+    url: string;
+    /** Total number of categories returned (after filtering) */
+    total: number;
+    /** Array of categories */
+    categories: IABCategory[];
+}
+interface GetCategoriesParams {
+    /** Filter by tier level (1-4) */
+    tier?: 1 | 2 | 3 | 4;
+    /** Filter by parent category ID */
+    parent_id?: number;
+    /** Search by name or path (case-insensitive) */
+    search?: string;
+}
 
 /**
  * Utility functions for the AttentionMarket SDK.
@@ -981,6 +1060,39 @@ declare class AttentionMarketClient {
      * ```
      */
     logServiceResult(params: ServiceResultRequest): Promise<ServiceResultResponse>;
+    /**
+     * Get IAB Content Taxonomy categories.
+     *
+     * Returns the complete IAB Content Taxonomy 3.0 (704 categories across 38 top-level categories).
+     * Supports filtering by tier level, parent category, or search term.
+     *
+     * Use this to discover available categories for `allowedCategories` and `blockedCategories` parameters.
+     *
+     * @param params - Optional filters (tier, parent_id, search)
+     * @returns The IAB Content Taxonomy with categories
+     *
+     * @example Get all Tier 1 categories (38 top-level categories)
+     * ```typescript
+     * const tier1 = await client.getCategories({ tier: 1 });
+     * console.log(`${tier1.total} top-level categories`);
+     * tier1.categories.forEach(cat => console.log(`${cat.id}: ${cat.name}`));
+     * ```
+     *
+     * @example Get all subcategories of "Automotive" (ID: 1)
+     * ```typescript
+     * const automotiveCategories = await client.getCategories({ parent_id: 1 });
+     * console.log(`Found ${automotiveCategories.total} automotive subcategories`);
+     * ```
+     *
+     * @example Search for insurance-related categories
+     * ```typescript
+     * const insuranceCategories = await client.getCategories({ search: 'insurance' });
+     * insuranceCategories.categories.forEach(cat => {
+     *   console.log(`${cat.id}: ${cat.full_path}`);
+     * });
+     * ```
+     */
+    getCategories(params?: GetCategoriesParams): Promise<CategoryTaxonomyResponse>;
 }
 
 /**