@the_ro_show/agent-ads-sdk 0.4.0 → 0.4.2

package/SIMPLE_INTEGRATION_GUIDE.md

@@ -7,26 +7,19 @@ Your bot answers user questions. Sometimes those answers could include a helpful
 
 ## Step-by-Step Guide
 
-### **Step 1: Sign Up for API Keys** (One-time, 2 minutes)
+### **Step 1: Sign Up for API Keys** (One-time, 30 seconds)
 
 You need permission to request ads. Think of this like getting a key to a vending machine.
 
 **How to do it:**
-```bash
-# Run this command once (it's like filling out a registration form)
-curl -X POST https://api.attentionmarket.ai/v1/agent-signup \
-  -H 'Content-Type: application/json' \
-  -d '{
-    "owner_email": "your-email@example.com",
-    "agent_name": "My Cool Bot",
-    "sdk_type": "typescript"
-  }'
-```
+1. Go to **[attentionmarket.com/signup](https://attentionmarket.com/signup)**
+2. Enter your email and agent name
+3. Click "Generate API Keys"
 
 **You'll get back:**
-- An **Agent ID** (like `agt_abc123`) - your username
 - A **Test Key** (like `am_test_xyz789`) - for testing
 - A **Live Key** (like `am_live_xyz789`) - for when you go live
+- An **Agent ID** (you'll use this for tracking)
 
 **Write these down!** You'll need them.
 
@@ -96,7 +89,7 @@ async function handleUserMessage(userMessage) {
         surface: 'chat'
       },
       opportunity: createOpportunity({
-        taxonomy: 'shopping.ecommerce.platform', // This matches Pietra!
+        taxonomy: 'business.ecommerce.platform.trial', // E-commerce platforms
         country: 'US',
         language: 'en',
         platform: 'web',
@@ -204,8 +197,10 @@ await adClient.trackClick({
 
 ### **Taxonomy** = Topic Category
 When you request an ad, you tell us what the user is asking about:
-- `shopping.ecommerce.platform` = Online store questions
-- `local_services.movers.quote` = Moving company questions
+- `business.ecommerce.platform.trial` = Online store questions
+- `home_services.moving.local.quote` = Moving company questions
+- `insurance.auto.full_coverage.quote` = Car insurance questions
+- `legal.family.divorce.consultation` = Divorce lawyer questions
 - `business.productivity.tools` = Productivity software questions
 
 **You pick the taxonomy** based on what the user asked.
@@ -255,7 +250,7 @@ async function handleMessage(userMessage) {
       agent_id: process.env.ATTENTIONMARKET_AGENT_ID,
       placement: { type: 'sponsored_suggestion', surface: 'chat' },
       opportunity: createOpportunity({
-        taxonomy: 'shopping.ecommerce.platform',
+        taxonomy: 'business.ecommerce.platform.trial',
         country: 'US',
         language: 'en',
         platform: 'web',

package/dist/index.d.mts

@@ -21,6 +21,48 @@ interface DecideRequest {
     agent_id: string;
     placement: Placement;
     opportunity: Opportunity;
+    /** Full conversation context for semantic matching (optional) */
+    context?: string;
+    /** Detected or inferred user intent for semantic matching (optional) */
+    user_intent?: string;
+}
+/**
+ * Simplified request for semantic context-based ad matching.
+ * Uses conversation context instead of manual taxonomy selection.
+ *
+ * The SDK automatically limits conversationHistory to the last 5 messages
+ * to avoid token overflow. Only userMessage is required.
+ *
+ * @example
+ * ```typescript
+ * const ad = await client.decideFromContext({
+ *   userMessage: "I need help with estate planning",
+ *   conversationHistory: ["User: My father passed away recently"],
+ *   placement: 'sponsored_suggestion'
+ * });
+ * ```
+ */
+interface DecideFromContextRequest {
+    /** The user's current message (required) */
+    userMessage: string;
+    /**
+     * Optional conversation history (last few messages for context).
+     * SDK automatically limits to last 5 messages to avoid token overflow.
+     */
+    conversationHistory?: string[];
+    /** Ad placement type. Default: 'sponsored_suggestion' */
+    placement?: PlacementType;
+    /**
+     * Optional category hint (e.g., 'legal', 'insurance', 'travel').
+     * Used as fallback if semantic matching fails.
+     */
+    suggestedCategory?: string;
+    /** User's country code. Default: 'US' */
+    country?: string;
+    /** User's language code. Default: 'en' */
+    language?: string;
+    /** User's platform. Default: 'web' */
+    platform?: 'web' | 'ios' | 'android' | 'desktop' | 'voice' | 'other';
 }
 interface DecideResponse {
     request_id: string;
@@ -154,6 +196,7 @@ interface APIError {
 }
 interface SDKConfig {
     apiKey: string;
+    agentId?: string;
     supabaseAnonKey?: string;
     baseUrl?: string;
     timeoutMs?: number;
@@ -313,6 +356,7 @@ declare function sanitizeURL(url: string | null | undefined, options?: SanitizeU
 
 declare class AttentionMarketClient {
     private http;
+    private agentId;
     constructor(config: SDKConfig);
     /**
      * Validate SDK configuration for security
@@ -332,6 +376,23 @@ declare class AttentionMarketClient {
     decide(request: DecideRequest, options?: {
         idempotencyKey?: string;
     }): Promise<AdUnit | null>;
+    /**
+     * Simplified ad matching using conversation context and semantic search.
+     * Automatically handles request construction, taxonomy fallback, and defaults.
+     *
+     * Requires: agentId in SDKConfig constructor
+     *
+     * @example
+     * const ad = await client.decideFromContext({
+     *   userMessage: "My father passed away and I need help organizing his estate",
+     *   placement: 'sponsored_suggestion'
+     * });
+     *
+     * @throws {Error} If agentId was not provided in SDKConfig
+     */
+    decideFromContext(params: DecideFromContextRequest, options?: {
+        idempotencyKey?: string;
+    }): Promise<AdUnit | null>;
     /**
      * Report an event (impression, click, action, conversion, feedback).
      */
@@ -644,4 +705,4 @@ declare function getVertical(taxonomy: string): string | null;
  */
 declare function suggestTaxonomies(query: string): string[];
 
-export { type APIError, APIRequestError, type AdScore, type AdUnit, type AgentSignupRequest, type AgentSignupResponse, AttentionMarketClient, AttentionMarketError, type Constraints, type Context, type CreateClickEventParams, type CreateImpressionEventParams, type CreateOpportunityParams, type DecideRequest, type DecideResponse, type Disclosure, type EventIngestRequest, type EventIngestResponse, type EventType, type Intent, MockAttentionMarketClient, type MockClientConfig, NetworkError, type Opportunity, type ParsedTaxonomy, type Placement, type PlacementType, type PolicyResponse, type Privacy, type SDKConfig, type SanitizeURLOptions, type SponsoredSuggestion, type SponsoredTool, type TaxonomyIntent, TimeoutError, type ToolCall, type Tracking, buildTaxonomy, createClickEvent, createImpressionEvent, createOpportunity, detectIntent, escapeHTML, generateTimestamp, generateUUID, getBaseTaxonomy, getVertical, isValidTaxonomy, matchesTaxonomy, parseTaxonomy, sanitizeURL, suggestTaxonomies };
+export { type APIError, APIRequestError, type AdScore, type AdUnit, type AgentSignupRequest, type AgentSignupResponse, AttentionMarketClient, AttentionMarketError, type Constraints, type Context, type CreateClickEventParams, type CreateImpressionEventParams, type CreateOpportunityParams, type DecideFromContextRequest, type DecideRequest, type DecideResponse, type Disclosure, type EventIngestRequest, type EventIngestResponse, type EventType, type Intent, MockAttentionMarketClient, type MockClientConfig, NetworkError, type Opportunity, type ParsedTaxonomy, type Placement, type PlacementType, type PolicyResponse, type Privacy, type SDKConfig, type SanitizeURLOptions, type SponsoredSuggestion, type SponsoredTool, type TaxonomyIntent, TimeoutError, type ToolCall, type Tracking, buildTaxonomy, createClickEvent, createImpressionEvent, createOpportunity, detectIntent, escapeHTML, generateTimestamp, generateUUID, getBaseTaxonomy, getVertical, isValidTaxonomy, matchesTaxonomy, parseTaxonomy, sanitizeURL, suggestTaxonomies };

package/dist/index.d.ts

@@ -21,6 +21,48 @@ interface DecideRequest {
     agent_id: string;
     placement: Placement;
     opportunity: Opportunity;
+    /** Full conversation context for semantic matching (optional) */
+    context?: string;
+    /** Detected or inferred user intent for semantic matching (optional) */
+    user_intent?: string;
+}
+/**
+ * Simplified request for semantic context-based ad matching.
+ * Uses conversation context instead of manual taxonomy selection.
+ *
+ * The SDK automatically limits conversationHistory to the last 5 messages
+ * to avoid token overflow. Only userMessage is required.
+ *
+ * @example
+ * ```typescript
+ * const ad = await client.decideFromContext({
+ *   userMessage: "I need help with estate planning",
+ *   conversationHistory: ["User: My father passed away recently"],
+ *   placement: 'sponsored_suggestion'
+ * });
+ * ```
+ */
+interface DecideFromContextRequest {
+    /** The user's current message (required) */
+    userMessage: string;
+    /**
+     * Optional conversation history (last few messages for context).
+     * SDK automatically limits to last 5 messages to avoid token overflow.
+     */
+    conversationHistory?: string[];
+    /** Ad placement type. Default: 'sponsored_suggestion' */
+    placement?: PlacementType;
+    /**
+     * Optional category hint (e.g., 'legal', 'insurance', 'travel').
+     * Used as fallback if semantic matching fails.
+     */
+    suggestedCategory?: string;
+    /** User's country code. Default: 'US' */
+    country?: string;
+    /** User's language code. Default: 'en' */
+    language?: string;
+    /** User's platform. Default: 'web' */
+    platform?: 'web' | 'ios' | 'android' | 'desktop' | 'voice' | 'other';
 }
 interface DecideResponse {
     request_id: string;
@@ -154,6 +196,7 @@ interface APIError {
 }
 interface SDKConfig {
     apiKey: string;
+    agentId?: string;
     supabaseAnonKey?: string;
     baseUrl?: string;
     timeoutMs?: number;
@@ -313,6 +356,7 @@ declare function sanitizeURL(url: string | null | undefined, options?: SanitizeU
 
 declare class AttentionMarketClient {
     private http;
+    private agentId;
     constructor(config: SDKConfig);
     /**
      * Validate SDK configuration for security
@@ -332,6 +376,23 @@ declare class AttentionMarketClient {
     decide(request: DecideRequest, options?: {
         idempotencyKey?: string;
     }): Promise<AdUnit | null>;
+    /**
+     * Simplified ad matching using conversation context and semantic search.
+     * Automatically handles request construction, taxonomy fallback, and defaults.
+     *
+     * Requires: agentId in SDKConfig constructor
+     *
+     * @example
+     * const ad = await client.decideFromContext({
+     *   userMessage: "My father passed away and I need help organizing his estate",
+     *   placement: 'sponsored_suggestion'
+     * });
+     *
+     * @throws {Error} If agentId was not provided in SDKConfig
+     */
+    decideFromContext(params: DecideFromContextRequest, options?: {
+        idempotencyKey?: string;
+    }): Promise<AdUnit | null>;
     /**
      * Report an event (impression, click, action, conversion, feedback).
      */
@@ -644,4 +705,4 @@ declare function getVertical(taxonomy: string): string | null;
  */
 declare function suggestTaxonomies(query: string): string[];
 
-export { type APIError, APIRequestError, type AdScore, type AdUnit, type AgentSignupRequest, type AgentSignupResponse, AttentionMarketClient, AttentionMarketError, type Constraints, type Context, type CreateClickEventParams, type CreateImpressionEventParams, type CreateOpportunityParams, type DecideRequest, type DecideResponse, type Disclosure, type EventIngestRequest, type EventIngestResponse, type EventType, type Intent, MockAttentionMarketClient, type MockClientConfig, NetworkError, type Opportunity, type ParsedTaxonomy, type Placement, type PlacementType, type PolicyResponse, type Privacy, type SDKConfig, type SanitizeURLOptions, type SponsoredSuggestion, type SponsoredTool, type TaxonomyIntent, TimeoutError, type ToolCall, type Tracking, buildTaxonomy, createClickEvent, createImpressionEvent, createOpportunity, detectIntent, escapeHTML, generateTimestamp, generateUUID, getBaseTaxonomy, getVertical, isValidTaxonomy, matchesTaxonomy, parseTaxonomy, sanitizeURL, suggestTaxonomies };
+export { type APIError, APIRequestError, type AdScore, type AdUnit, type AgentSignupRequest, type AgentSignupResponse, AttentionMarketClient, AttentionMarketError, type Constraints, type Context, type CreateClickEventParams, type CreateImpressionEventParams, type CreateOpportunityParams, type DecideFromContextRequest, type DecideRequest, type DecideResponse, type Disclosure, type EventIngestRequest, type EventIngestResponse, type EventType, type Intent, MockAttentionMarketClient, type MockClientConfig, NetworkError, type Opportunity, type ParsedTaxonomy, type Placement, type PlacementType, type PolicyResponse, type Privacy, type SDKConfig, type SanitizeURLOptions, type SponsoredSuggestion, type SponsoredTool, type TaxonomyIntent, TimeoutError, type ToolCall, type Tracking, buildTaxonomy, createClickEvent, createImpressionEvent, createOpportunity, detectIntent, escapeHTML, generateTimestamp, generateUUID, getBaseTaxonomy, getVertical, isValidTaxonomy, matchesTaxonomy, parseTaxonomy, sanitizeURL, suggestTaxonomies };

package/dist/index.js

@@ -354,7 +354,9 @@ var DEFAULT_TIMEOUT_MS = 4e3;
 var DEFAULT_MAX_RETRIES = 2;
 var AttentionMarketClient = class {
   http;
+  agentId;
   constructor(config) {
+    this.agentId = config.agentId;
     this.validateConfig(config);
     const httpConfig = {
       apiKey: config.apiKey,
@@ -408,6 +410,66 @@ var AttentionMarketClient = class {
     }
     return response.units[0] ?? null;
   }
+  /**
+   * Simplified ad matching using conversation context and semantic search.
+   * Automatically handles request construction, taxonomy fallback, and defaults.
+   *
+   * Requires: agentId in SDKConfig constructor
+   *
+   * @example
+   * const ad = await client.decideFromContext({
+   *   userMessage: "My father passed away and I need help organizing his estate",
+   *   placement: 'sponsored_suggestion'
+   * });
+   *
+   * @throws {Error} If agentId was not provided in SDKConfig
+   */
+  async decideFromContext(params, options) {
+    if (!this.agentId) {
+      throw new Error(
+        "decideFromContext() requires agentId to be set in SDKConfig. Either provide agentId in the constructor or use decide() directly."
+      );
+    }
+    const historyLimit = 5;
+    const history = params.conversationHistory || [];
+    const limitedHistory = history.slice(-historyLimit);
+    const contextParts = [...limitedHistory, params.userMessage];
+    const context = contextParts.join("\n");
+    const country = params.country || "US";
+    const language = params.language || "en";
+    const platform = params.platform || "web";
+    const placementType = params.placement || "sponsored_suggestion";
+    const taxonomy = params.suggestedCategory || "unknown";
+    const request = {
+      request_id: generateUUID(),
+      agent_id: this.agentId,
+      placement: {
+        type: placementType,
+        surface: "chat"
+      },
+      opportunity: {
+        intent: {
+          taxonomy,
+          query: params.userMessage
+        },
+        context: {
+          country,
+          language,
+          platform
+        },
+        constraints: {
+          max_units: 1,
+          allowed_unit_types: [placementType]
+        },
+        privacy: {
+          data_policy: "coarse_only"
+        }
+      },
+      context,
+      user_intent: params.userMessage
+    };
+    return await this.decide(request, options);
+  }
   /**
    * Report an event (impression, click, action, conversion, feedback).
    */