@the_ro_show/agent-ads-sdk 0.13.0 → 0.13.1

package/README.md

@@ -500,7 +500,17 @@ const ad = await client.decideFromContext({
 - 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.
+**Important:**
+- If `allowedCategories` is set, `blockedCategories` is ignored
+- IAB category IDs (numbers) are **recommended** - legacy string categories are deprecated (support ends 2026-06-01)
+- Use `getCategories()` API to discover category IDs
+- Empty `allowedCategories: []` is rejected (would block all ads - use `blockedCategories` instead)
+
+**Validation rules:**
+- `minQualityScore`: Must be 0.0-1.0
+- `allowedCategories`: Must be non-empty array of strings or numbers
+- `blockedCategories`: Must be array of strings or numbers
+- `blockedAdvertisers`: Must be array of non-empty strings (advertiser IDs)
 
 ### Advertiser Blocklist
 
@@ -515,16 +525,111 @@ const ad = await client.decideFromContext({
 
 Get advertiser IDs from previous ad responses.
 
-### Combined Controls
+## 💰 Revenue Optimization (v0.13.1+)
+
+Control revenue vs. relevance tradeoffs with bid and relevance filters.
+
+### Minimum CPC Filter
+
+Only show ads above a minimum bid threshold:
+
+```typescript
+const ad = await client.decideFromContext({
+  userMessage: "I need car insurance",
+  minCPC: 100  // Only ads bidding ≥$1.00 per click
+});
+```
+
+**Use cases:**
+- **Premium apps**: `minCPC: 200` for $2+ ads only
+- **High-value verticals**: Filter out low-budget advertisers
+- **Revenue targets**: Ensure minimum revenue per impression
+
+### Minimum Relevance Score
+
+Only show ads that are semantically relevant:
+
+```typescript
+const ad = await client.decideFromContext({
+  userMessage: "Help me plan my wedding",
+  minRelevanceScore: 0.8  // Only highly relevant ads (0.0-1.0)
+});
+```
+
+**Use cases:**
+- **Niche apps**: Legal assistant = `0.8+` for specialized content only
+- **User experience**: Filter out loosely related ads
+- **Context matching**: Ensure ads match conversation topic
+- **Default threshold**: Backend uses 0.25 minimum
+
+### Ranking Strategy
+
+Choose how ads are ranked:
+
+```typescript
+// Default: Revenue-optimized (highest bid wins)
+const ad = await client.decideFromContext({
+  userMessage: "I need legal help",
+  optimizeFor: 'revenue'  // Rank by bid × quality × relevance
+});
+
+// Alternative: Relevance-optimized (best match wins)
+const ad = await client.decideFromContext({
+  userMessage: "I need legal help",
+  optimizeFor: 'relevance'  // Rank by semantic similarity only
+});
+```
+
+**Use cases:**
+- **General apps**: `'revenue'` to maximize earnings
+- **Niche apps**: `'relevance'` to prioritize perfect matches over high bids
+- **Premium experiences**: Combine with high `minRelevanceScore` + `'relevance'` ranking
+
+**How it works (second-price auction):**
+- **Revenue mode**: Winner ranked by composite score (bid × quality × relevance), pays just enough to beat next ad's composite score + $0.01
+- **Relevance mode**: Winner ranked by semantic similarity, pays just enough to beat next ad in the composite score space + $0.01
+- **Always capped**: Winner never pays more than their max bid (auction integrity guaranteed)
+- **Floor price**: Minimum $0.25 clearing price ensures platform revenue
+
+**Important notes:**
+- `minRelevanceScore` only applies to campaigns with semantic targeting
+- For keyword/automatic campaigns, relevance filter has no effect
+- Validation errors return HTTP 400 with clear messages
+
+### Combined Revenue Controls
+
+```typescript
+// Premium legal assistant: High relevance + high bids
+const ad = await client.decideFromContext({
+  userMessage: "I need estate planning help",
+  minRelevanceScore: 0.8,  // Only highly relevant
+  minCPC: 200,             // Only $2+ bids
+  optimizeFor: 'relevance', // Best match wins
+  allowedCategories: [318] // Legal services only (IAB)
+});
+
+// General chatbot: Maximize revenue
+const ad = await client.decideFromContext({
+  userMessage: "Help me with something",
+  optimizeFor: 'revenue',  // Highest bid wins
+  minQualityScore: 0.7     // Decent quality threshold
+});
+```
+
+### Combined Controls (All Phases)
 
 Mix and match for precise control:
 
 ```typescript
 const ad = await client.decideFromContext({
   userMessage: "I need car insurance",
+  // Phase 1: Quality & Brand Safety
   minQualityScore: 0.8,           // High quality only
-  blockedCategories: ['crypto'],   // No crypto ads
-  allowedCategories: ['insurance', 'finance']  // Relevant only
+  allowedCategories: [31, 398],   // Auto + Personal Finance Insurance (IAB)
+  // Phase 2: Revenue Optimization
+  minCPC: 50,                      // $0.50+ bids only
+  minRelevanceScore: 0.7,          // Highly relevant only
+  optimizeFor: 'revenue'           // Highest bid wins
 });
 ```
 

package/dist/index.d.mts

@@ -96,6 +96,35 @@ interface DecideFromContextRequest {
      * blockedAdvertisers: ['adv_abc123', 'adv_xyz789']
      */
     blockedAdvertisers?: string[];
+    /**
+     * Minimum cost-per-click threshold in cents.
+     * Only return ads with bids at or above this value.
+     * Higher values = more revenue per ad but lower fill rate.
+     *
+     * @example
+     * minCPC: 50  // Only show ads bidding $0.50 or more per click
+     */
+    minCPC?: number;
+    /**
+     * Minimum semantic relevance score threshold (0.0 - 1.0).
+     * Only return ads with relevance scores at or above this value.
+     * Higher values = more relevant ads but lower fill rate.
+     * Default backend threshold: 0.25
+     *
+     * @example
+     * minRelevanceScore: 0.8  // Only show highly relevant ads
+     */
+    minRelevanceScore?: number;
+    /**
+     * Ad ranking strategy.
+     * - 'revenue': Rank by bid amount (highest bid wins)
+     * - 'relevance': Rank by semantic similarity (best match wins)
+     * Default: 'revenue'
+     *
+     * @example
+     * optimizeFor: 'relevance'  // Prioritize best semantic match over highest bid
+     */
+    optimizeFor?: 'revenue' | 'relevance';
 }
 interface DecideResponse {
     request_id: string;

package/dist/index.d.ts

@@ -96,6 +96,35 @@ interface DecideFromContextRequest {
      * blockedAdvertisers: ['adv_abc123', 'adv_xyz789']
      */
     blockedAdvertisers?: string[];
+    /**
+     * Minimum cost-per-click threshold in cents.
+     * Only return ads with bids at or above this value.
+     * Higher values = more revenue per ad but lower fill rate.
+     *
+     * @example
+     * minCPC: 50  // Only show ads bidding $0.50 or more per click
+     */
+    minCPC?: number;
+    /**
+     * Minimum semantic relevance score threshold (0.0 - 1.0).
+     * Only return ads with relevance scores at or above this value.
+     * Higher values = more relevant ads but lower fill rate.
+     * Default backend threshold: 0.25
+     *
+     * @example
+     * minRelevanceScore: 0.8  // Only show highly relevant ads
+     */
+    minRelevanceScore?: number;
+    /**
+     * Ad ranking strategy.
+     * - 'revenue': Rank by bid amount (highest bid wins)
+     * - 'relevance': Rank by semantic similarity (best match wins)
+     * Default: 'revenue'
+     *
+     * @example
+     * optimizeFor: 'relevance'  // Prioritize best semantic match over highest bid
+     */
+    optimizeFor?: 'revenue' | 'relevance';
 }
 interface DecideResponse {
     request_id: string;

package/dist/index.js

@@ -503,6 +503,60 @@ var AttentionMarketClient = class {
     const platform = params.platform || "web";
     const placementType = params.placement || "sponsored_suggestion";
     const taxonomy = params.suggestedCategory || this.inferTaxonomy(params.userMessage);
+    if (params.minQualityScore !== void 0) {
+      if (typeof params.minQualityScore !== "number" || params.minQualityScore < 0 || params.minQualityScore > 1) {
+        throw new Error("minQualityScore must be a number between 0.0 and 1.0");
+      }
+    }
+    if (params.allowedCategories !== void 0) {
+      if (!Array.isArray(params.allowedCategories)) {
+        throw new Error("allowedCategories must be an array");
+      }
+      if (params.allowedCategories.length === 0) {
+        throw new Error("allowedCategories cannot be empty (would block all ads). Use blockedCategories to exclude specific categories, or omit to allow all.");
+      }
+      for (const cat of params.allowedCategories) {
+        if (typeof cat !== "string" && typeof cat !== "number") {
+          throw new Error(`allowedCategories must contain strings or numbers, found: ${typeof cat}`);
+        }
+      }
+    }
+    if (params.blockedCategories !== void 0) {
+      if (!Array.isArray(params.blockedCategories)) {
+        throw new Error("blockedCategories must be an array");
+      }
+      for (const cat of params.blockedCategories) {
+        if (typeof cat !== "string" && typeof cat !== "number") {
+          throw new Error(`blockedCategories must contain strings or numbers, found: ${typeof cat}`);
+        }
+      }
+      if (params.allowedCategories && params.allowedCategories.length > 0) {
+        console.warn("[AttentionMarket] Both allowedCategories and blockedCategories specified. blockedCategories will be ignored.");
+      }
+    }
+    if (params.blockedAdvertisers !== void 0) {
+      if (!Array.isArray(params.blockedAdvertisers)) {
+        throw new Error("blockedAdvertisers must be an array");
+      }
+      for (const id of params.blockedAdvertisers) {
+        if (typeof id !== "string" || id.trim().length === 0) {
+          throw new Error("blockedAdvertisers must contain non-empty strings (advertiser IDs)");
+        }
+      }
+    }
+    if (params.minCPC !== void 0) {
+      if (typeof params.minCPC !== "number" || params.minCPC < 0) {
+        throw new Error("minCPC must be a non-negative number (cost-per-click in cents)");
+      }
+    }
+    if (params.minRelevanceScore !== void 0) {
+      if (typeof params.minRelevanceScore !== "number" || params.minRelevanceScore < 0 || params.minRelevanceScore > 1) {
+        throw new Error("minRelevanceScore must be a number between 0.0 and 1.0");
+      }
+    }
+    if (params.optimizeFor && params.optimizeFor !== "revenue" && params.optimizeFor !== "relevance") {
+      throw new Error('optimizeFor must be either "revenue" or "relevance"');
+    }
     const request = {
       request_id: generateUUID(),
       agent_id: this.agentId,
@@ -534,7 +588,11 @@ var AttentionMarketClient = class {
       ...params.minQualityScore !== void 0 && { minQualityScore: params.minQualityScore },
       ...params.allowedCategories && { allowedCategories: params.allowedCategories },
       ...params.blockedCategories && { blockedCategories: params.blockedCategories },
-      ...params.blockedAdvertisers && { blockedAdvertisers: params.blockedAdvertisers }
+      ...params.blockedAdvertisers && { blockedAdvertisers: params.blockedAdvertisers },
+      // Developer controls (Phase 2: Revenue Optimization)
+      ...params.minCPC !== void 0 && { minCPC: params.minCPC },
+      ...params.minRelevanceScore !== void 0 && { minRelevanceScore: params.minRelevanceScore },
+      ...params.optimizeFor && { optimizeFor: params.optimizeFor }
     };
     const response = await this.decideRaw(request, options);
     if (response.status === "no_fill" || response.units.length === 0) {