@the_ro_show/agent-ads-sdk 0.11.0 → 0.13.1

package/README.md

@@ -418,6 +418,255 @@ 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
+
+**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
+
+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.
+
+## 💰 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
+  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
+});
+```
+
+### 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,68 @@ 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[];
+    /**
+     * 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;
@@ -557,6 +619,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 +1089,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,68 @@ 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[];
+    /**
+     * 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;
@@ -557,6 +619,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 +1089,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

@@ -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,
@@ -529,7 +583,16 @@ 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 },
+      // 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) {
@@ -1156,6 +1219,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