@the_ro_show/agent-ads-sdk 0.11.0 → 0.13.0

package/README.md

@@ -418,6 +418,150 @@ curl -X POST https://peruwnbrqkvmrldhpoom.supabase.co/functions/v1/feedback \
 
 ---
 
+## 🎛️ 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;
@@ -557,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.
@@ -989,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;
@@ -557,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.
@@ -989,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.js

@@ -529,7 +529,12 @@ var AttentionMarketClient = class {
         }
       },
       context,
-      user_intent: params.userMessage
+      user_intent: params.userMessage,
+      // Developer controls (Phase 1: Quality & Brand Safety)
+      ...params.minQualityScore !== void 0 && { minQualityScore: params.minQualityScore },
+      ...params.allowedCategories && { allowedCategories: params.allowedCategories },
+      ...params.blockedCategories && { blockedCategories: params.blockedCategories },
+      ...params.blockedAdvertisers && { blockedAdvertisers: params.blockedAdvertisers }
     };
     const response = await this.decideRaw(request, options);
     if (response.status === "no_fill" || response.units.length === 0) {
@@ -1156,6 +1161,55 @@ var AttentionMarketClient = class {
       { body: params }
     );
   }
+  /**
+   * 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}`);
+   * });
+   * ```
+   */
+  async getCategories(params) {
+    const queryParams = new URLSearchParams();
+    if (params?.tier) {
+      queryParams.append("tier", params.tier.toString());
+    }
+    if (params?.parent_id) {
+      queryParams.append("parent_id", params.parent_id.toString());
+    }
+    if (params?.search) {
+      queryParams.append("search", params.search);
+    }
+    const url = `/v1/categories${queryParams.toString() ? "?" + queryParams.toString() : ""}`;
+    return await this.http.request(
+      "GET",
+      url
+    );
+  }
 };
 
 // src/mock-client.ts