@the_ro_show/agent-ads-sdk 0.4.1 → 0.4.3

package/README.md

@@ -1,6 +1,15 @@
 # AttentionMarket Agent Ads SDK
 
-TypeScript SDK for monetizing AI agents with relevant sponsored content. Earn $5-50 per click.
+[![npm version](https://badge.fury.io/js/@the_ro_show%2Fagent-ads-sdk.svg)](https://www.npmjs.com/package/@the_ro_show/agent-ads-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+
+**The first ad network built for AI agents.** Monetize your AI agent with contextual, high-intent sponsored suggestions. Open source, transparent, developer-first.
+
+- 🚀 **5-minute integration** - npm install + 5 lines of code
+- 💰 **70% revenue share** - You keep the majority, we only win when you do
+- 🎯 **10-15% CTR** - High-intent placements, not banner ads
+- 🔓 **100% Open Source** - Audit every line, full transparency
 
 ## Quick Start
 

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).
      */
@@ -487,6 +548,127 @@ declare class TimeoutError extends AttentionMarketError {
     constructor(message?: string);
 }
 
+/**
+ * Natural ad formatting utilities
+ *
+ * Transforms ad copy to feel more conversational while preserving
+ * all tracking data and disclosure requirements.
+ */
+
+interface NaturalFormatOptions {
+    /**
+     * Tone/style for the formatted text
+     * - 'conversational': Friendly, natural language
+     * - 'helpful': Informative assistant tone
+     * - 'direct': Clear and concise
+     */
+    style?: 'conversational' | 'helpful' | 'direct';
+    /**
+     * Optional user context to make formatting more relevant
+     * Example: "User is looking for estate planning help"
+     */
+    userContext?: string;
+    /**
+     * Maximum length for formatted text (characters)
+     * Will truncate gracefully if needed
+     */
+    maxLength?: number;
+    /**
+     * Whether to include the disclosure inline
+     * Default: true (always show sponsored label)
+     */
+    includeDisclosure?: boolean;
+}
+interface FormattedAd {
+    /**
+     * Naturally formatted text suitable for conversation
+     */
+    text: string;
+    /**
+     * Call-to-action text
+     */
+    cta: string;
+    /**
+     * Action URL (preserved from original ad)
+     */
+    actionUrl: string;
+    /**
+     * Tracking data (preserved from original ad)
+     * IMPORTANT: Pass this to trackClick() when user clicks
+     */
+    tracking: {
+        eventId: string;
+        trackingToken: string;
+        decisionId: string;
+    };
+    /**
+     * Disclosure information (preserved from original ad)
+     */
+    disclosure: {
+        label: string;
+        sponsorName: string;
+    };
+}
+/**
+ * Format an ad unit into natural conversational text.
+ * Preserves all tracking data and disclosure requirements.
+ *
+ * @example
+ * ```typescript
+ * const ad = await client.decide({...});
+ * const formatted = formatNatural(ad, {
+ *   style: 'conversational',
+ *   userContext: "User needs estate planning help"
+ * });
+ *
+ * console.log(formatted.text);
+ * // "I found a service that might help: [Title]. [Body]"
+ *
+ * // When user clicks, tracking still works:
+ * await client.trackClick({
+ *   event_id: formatted.tracking.eventId,
+ *   tracking_token: formatted.tracking.trackingToken
+ * });
+ * ```
+ */
+declare function formatNatural(ad: AdUnit, options?: NaturalFormatOptions): FormattedAd;
+/**
+ * Extract just the essential info from an ad for inline mentions.
+ * Useful when you want to reference an ad without showing the full text.
+ *
+ * @example
+ * ```typescript
+ * const mention = formatInlineMention(ad);
+ * console.log(`You might want to check out ${mention.text}`);
+ * // "You might want to check out Estate Planning Services (Sponsored)"
+ * ```
+ */
+declare function formatInlineMention(ad: AdUnit): FormattedAd;
+/**
+ * Validate that an ad fits within UI constraints.
+ * Helps developers check if ad will display correctly before showing it.
+ *
+ * @example
+ * ```typescript
+ * const validation = validateAdFits(ad, {
+ *   maxTitleChars: 60,
+ *   maxBodyChars: 200
+ * });
+ *
+ * if (!validation.fits) {
+ *   console.log('Ad too long:', validation.violations);
+ * }
+ * ```
+ */
+declare function validateAdFits(ad: AdUnit, constraints: {
+    maxTitleChars?: number;
+    maxBodyChars?: number;
+    maxCtaChars?: number;
+}): {
+    fits: boolean;
+    violations: string[];
+};
+
 /**
  * Taxonomy helper utilities for AttentionMarket SDK
  * Helps with building, validating, and working with the 4-tier taxonomy system
@@ -644,4 +826,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 FormattedAd, type Intent, MockAttentionMarketClient, type MockClientConfig, type NaturalFormatOptions, 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, formatInlineMention, formatNatural, generateTimestamp, generateUUID, getBaseTaxonomy, getVertical, isValidTaxonomy, matchesTaxonomy, parseTaxonomy, sanitizeURL, suggestTaxonomies, validateAdFits };

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).
      */
@@ -487,6 +548,127 @@ declare class TimeoutError extends AttentionMarketError {
     constructor(message?: string);
 }
 
+/**
+ * Natural ad formatting utilities
+ *
+ * Transforms ad copy to feel more conversational while preserving
+ * all tracking data and disclosure requirements.
+ */
+
+interface NaturalFormatOptions {
+    /**
+     * Tone/style for the formatted text
+     * - 'conversational': Friendly, natural language
+     * - 'helpful': Informative assistant tone
+     * - 'direct': Clear and concise
+     */
+    style?: 'conversational' | 'helpful' | 'direct';
+    /**
+     * Optional user context to make formatting more relevant
+     * Example: "User is looking for estate planning help"
+     */
+    userContext?: string;
+    /**
+     * Maximum length for formatted text (characters)
+     * Will truncate gracefully if needed
+     */
+    maxLength?: number;
+    /**
+     * Whether to include the disclosure inline
+     * Default: true (always show sponsored label)
+     */
+    includeDisclosure?: boolean;
+}
+interface FormattedAd {
+    /**
+     * Naturally formatted text suitable for conversation
+     */
+    text: string;
+    /**
+     * Call-to-action text
+     */
+    cta: string;
+    /**
+     * Action URL (preserved from original ad)
+     */
+    actionUrl: string;
+    /**
+     * Tracking data (preserved from original ad)
+     * IMPORTANT: Pass this to trackClick() when user clicks
+     */
+    tracking: {
+        eventId: string;
+        trackingToken: string;
+        decisionId: string;
+    };
+    /**
+     * Disclosure information (preserved from original ad)
+     */
+    disclosure: {
+        label: string;
+        sponsorName: string;
+    };
+}
+/**
+ * Format an ad unit into natural conversational text.
+ * Preserves all tracking data and disclosure requirements.
+ *
+ * @example
+ * ```typescript
+ * const ad = await client.decide({...});
+ * const formatted = formatNatural(ad, {
+ *   style: 'conversational',
+ *   userContext: "User needs estate planning help"
+ * });
+ *
+ * console.log(formatted.text);
+ * // "I found a service that might help: [Title]. [Body]"
+ *
+ * // When user clicks, tracking still works:
+ * await client.trackClick({
+ *   event_id: formatted.tracking.eventId,
+ *   tracking_token: formatted.tracking.trackingToken
+ * });
+ * ```
+ */
+declare function formatNatural(ad: AdUnit, options?: NaturalFormatOptions): FormattedAd;
+/**
+ * Extract just the essential info from an ad for inline mentions.
+ * Useful when you want to reference an ad without showing the full text.
+ *
+ * @example
+ * ```typescript
+ * const mention = formatInlineMention(ad);
+ * console.log(`You might want to check out ${mention.text}`);
+ * // "You might want to check out Estate Planning Services (Sponsored)"
+ * ```
+ */
+declare function formatInlineMention(ad: AdUnit): FormattedAd;
+/**
+ * Validate that an ad fits within UI constraints.
+ * Helps developers check if ad will display correctly before showing it.
+ *
+ * @example
+ * ```typescript
+ * const validation = validateAdFits(ad, {
+ *   maxTitleChars: 60,
+ *   maxBodyChars: 200
+ * });
+ *
+ * if (!validation.fits) {
+ *   console.log('Ad too long:', validation.violations);
+ * }
+ * ```
+ */
+declare function validateAdFits(ad: AdUnit, constraints: {
+    maxTitleChars?: number;
+    maxBodyChars?: number;
+    maxCtaChars?: number;
+}): {
+    fits: boolean;
+    violations: string[];
+};
+
 /**
  * Taxonomy helper utilities for AttentionMarket SDK
  * Helps with building, validating, and working with the 4-tier taxonomy system
@@ -644,4 +826,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 FormattedAd, type Intent, MockAttentionMarketClient, type MockClientConfig, type NaturalFormatOptions, 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, formatInlineMention, formatNatural, generateTimestamp, generateUUID, getBaseTaxonomy, getVertical, isValidTaxonomy, matchesTaxonomy, parseTaxonomy, sanitizeURL, suggestTaxonomies, validateAdFits };