@the_ro_show/agent-ads-sdk 0.16.1 → 0.17.0

package/README.md

@@ -46,6 +46,35 @@ if (ad) {
 }
 ```
 
+## How You Earn Money
+
+AttentionMarket pays you when users **click** sponsored content. It's that simple.
+
+### Revenue Formula
+```
+Your Earnings = Clicks × Payout Per Click
+```
+
+Every response shows exactly what you'll earn:
+```typescript
+{
+  "payout": 250,        // You earn $2.50 when clicked
+  "click_url": "https://...",
+  "creative": { title: "...", body: "..." }
+}
+```
+
+### Why We Track Impressions
+
+Impressions prevent click fraud. If sponsored content wasn't shown, clicks won't generate revenue.
+
+**Important:**
+- ✅ Impressions are **required** for clicks to count
+- ❌ Impressions do **NOT** generate revenue themselves
+- ✅ The SDK tracks impressions automatically
+
+Think of impressions as a receipt: "Yes, this content was actually shown to a real user."
+
 ## Smart Context (v0.15.1+) 🎯
 
 Improve ad relevance by 2-3x with smart context features that understand user intent better:
@@ -375,10 +404,10 @@ const ad = await client.decideFromContext({
 **Validation:** Must be a non-negative number.
 
 **Use cases:**
-- Premium applications: `200+` for $2+ ads only
+- Premium applications: `200+` for $2+ per click only
 - High-value verticals: Filter out low-budget advertisers
-- Revenue targets: Ensure minimum revenue per impression
-- Lower fill rate tolerance: When you'd rather show nothing than a low-value ad
+- Revenue targets: Ensure minimum earnings when clicked
+- Lower fill rate tolerance: When you'd rather show nothing than low-value content
 
 **Trade-off:** Higher thresholds = higher revenue per ad but lower fill rate.
 
@@ -586,6 +615,122 @@ await client.track({
 });
 ```
 
+### Developer Prediction System (Bonus Earnings)
+
+**Get paid more for accurate predictions!** After showing an ad, predict whether the user will convert. If you're right, earn a bonus:
+- ✅ Correct positive prediction → **+20% bonus**
+- ✅ Correct negative prediction → **+5% bonus**
+- ⚠️ Wrong prediction → No bonus (but no penalty)
+
+#### How It Works
+
+1. **Show the ad** to your user using `decideFromContext()`
+2. **Observe their reaction** (interested? asked questions? changed topic?)
+3. **Send feedback** with your prediction
+4. **Get bonus** 7 days later if you were right
+
+#### Option 1: Auto-Analysis (Recommended - Easiest)
+
+Just send the user's raw response, and our AI analyzes sentiment automatically:
+
+```typescript
+const ad = await client.decideFromContext({
+  userMessage: "I need car insurance",
+  placement: 'sponsored_suggestion'
+});
+
+// Show ad to user...
+// User responds: "Tell me more about that Geico offer!"
+
+await client.sendFeedback({
+  tracking_token: ad.tracking_token,
+  user_response: "Tell me more about that Geico offer!",
+  conversation_history: [
+    "User: I need car insurance",
+    "Agent: Check out Geico...",
+    "User: Tell me more about that Geico offer!"
+  ]
+});
+
+// Our AI detects: "positive" sentiment
+// You get base earnings + 20% bonus if user converts
+```
+
+**When to use:** You want simplicity. Let our AI handle sentiment analysis.
+
+#### Option 2: Manual Prediction (Advanced - Full Control)
+
+Analyze sentiment yourself and send your prediction:
+
+```typescript
+const ad = await client.decideFromContext({
+  userMessage: "I need car insurance",
+  placement: 'sponsored_suggestion'
+});
+
+// Show ad to user...
+// User responds: "No thanks, I already have insurance"
+
+// YOU analyze: User declined → predict negative
+await client.sendFeedback({
+  tracking_token: ad.tracking_token,
+  reaction: 'negative',  // You determine this
+  context: 'User already has insurance, politely declined'
+});
+
+// If user doesn't convert, you get +5% bonus
+```
+
+**When to use:** You want full control over sentiment classification, or you have your own sentiment analysis.
+
+#### Prediction Guidelines
+
+**Positive** - User shows interest:
+- "Tell me more!"
+- "How much does it cost?"
+- "Can you sign me up?"
+- Asks follow-up questions
+
+**Neutral** - Hard to tell:
+- "Maybe later"
+- "I'll think about it"
+- No clear response
+- Non-committal
+
+**Negative** - User not interested:
+- "No thanks"
+- "I already have that"
+- Changes topic immediately
+- Explicitly declines
+
+#### Response Format
+
+```typescript
+{
+  status: 'received',
+  feedback_id: 'evt_abc123',
+  potential_bonus: '20%',
+  resolution_date: '2026-03-13',
+  message: 'Feedback recorded. Bonus will be calculated after 7-day conversion window.',
+
+  // Only in auto-analysis mode:
+  sentiment_detected: 'positive',
+  analysis_mode: 'auto'
+}
+```
+
+#### Best Practices
+
+1. **Submit within 24 hours** - Feedback must be sent within 24 hours of showing the ad
+2. **One prediction per ad** - You can only submit feedback once per tracking_token
+3. **Be honest** - Don't predict "positive" for everything. Our system rewards accuracy, not volume
+4. **Use context** - Include conversation history for better auto-analysis
+5. **Skip when unsure** - No feedback is better than random guessing
+
+#### Cost of Auto-Analysis
+
+Auto-analysis costs ~$0.0001 per request (using GPT-3.5-turbo). We absorb this cost, so it's free for you. The better accuracy and developer experience is worth it.
+
 ## Error Handling
 
 The SDK throws errors for invalid configurations and failed requests:
@@ -704,6 +849,15 @@ Create a simple getRelevantAd(message) function that returns ads only when relev
 
 ## Changelog
 
+### v0.17.0 (2026-03-06) - AI-Powered Feedback Analysis
+- 🤖 **Auto-Analysis Mode:** Send raw user responses, our AI detects sentiment automatically
+- 💰 **Bonus Earnings:** +20% for correct positive predictions, +5% for correct negative predictions
+- 🔄 **Backward Compatible:** Existing manual `reaction` mode still supported
+- 📊 **Conversation Context:** Include conversation history for better sentiment analysis
+- ⚡ **Fast & Cheap:** GPT-3.5-turbo analysis (~$0.0001 per request, free for developers)
+- 🎯 **Fallback Logic:** Defaults to 'neutral' if AI analysis fails
+- 📝 **Enhanced Logging:** Track analysis_mode and sentiment_confidence in metadata
+
 ### v0.15.1 (2026-02-26) - Bug Fixes & Security
 - 🔒 Fixed session leak - sessionId now request-scoped, not instance-scoped
 - 🛡️ Added comprehensive input validation and sanitization

package/dist/index.d.mts

@@ -294,44 +294,63 @@ interface EventIngestRequest {
 interface EventIngestResponse {
     accepted: boolean;
 }
-/**
- * Sentiment types detected by backend AI analysis.
- *
- * - positive: User is interested/engaged (earn +15% if converts, -5% if not)
- * - neutral: User is indifferent (no bonus/penalty, data only)
- * - negative: User disliked the ad (no penalty, data only)
- */
-type FeedbackSentiment = 'positive' | 'neutral' | 'negative';
 /**
  * Send feedback on an ad after showing it to a user.
  *
- * **New in v0.11.0:** Backend analyzes sentiment automatically using AI.
- * Just send the user's actual response text - no need to classify it yourself.
+ * **Two modes available:**
  *
- * **Anti-Fraud:** Bonuses are deferred and validated against actual conversions.
- * - Correct positive prediction → +15% bonus after 7 days
- * - Wrong positive prediction → -5% penalty after 7 days
- * - Neutral/negative → no bonus/penalty (data only)
+ * **Auto-Analysis (Recommended):** Send the user's raw response, and our AI analyzes sentiment.
+ * ```typescript
+ * await client.sendFeedback({
+ *   tracking_token: ad.tracking_token,
+ *   user_response: "Tell me more about that!",
+ *   conversation_history: ["Previous message 1", "Previous message 2"]
+ * });
+ * ```
  *
- * @example
+ * **Manual Prediction:** Analyze sentiment yourself and send the prediction.
  * ```typescript
  * await client.sendFeedback({
  *   tracking_token: ad.tracking_token,
- *   user_response: "This looks perfect! How do I sign up?",
- *   agent_response: "Here's the signup link...",
- *   additional_context: "User spent 2 minutes reading the offer"
+ *   reaction: 'positive',  // You determine this
+ *   context: 'User asked follow-up questions'
  * });
  * ```
+ *
+ * **Bonuses (7-day deferred):**
+ * - Correct positive prediction → +20% bonus
+ * - Correct negative prediction → +5% bonus
+ * - Wrong prediction or no feedback → No bonus
  */
 interface FeedbackRequest {
-    /** Tracking token from the ad you showed */
+    /** Tracking token from the ad you showed (required) */
     tracking_token: string;
-    /** User's actual response text (required) */
-    user_response: string;
-    /** Your agent's response (optional, helps sentiment analysis) */
-    agent_response?: string;
-    /** Additional context about the interaction (optional) */
-    additional_context?: string;
+    /**
+     * OPTION 1 (Auto-Analysis): User's actual response text.
+     * Our AI will analyze sentiment and determine positive/neutral/negative.
+     * Max 2000 characters.
+     */
+    user_response?: string;
+    /**
+     * Conversation history for better context in auto-analysis.
+     * We use the last 3 messages to understand the conversation flow.
+     */
+    conversation_history?: string[];
+    /**
+     * OPTION 2 (Manual): Your prediction of user interest.
+     * Use this if you want full control over sentiment classification.
+     */
+    reaction?: 'positive' | 'neutral' | 'negative';
+    /**
+     * Additional context about the interaction (optional, both modes).
+     * Max 1000 characters.
+     */
+    context?: string;
+    /**
+     * Idempotency key for safe retries (optional).
+     * Use the same key if retrying a failed request to avoid duplicate feedback.
+     */
+    idempotency_key?: string;
 }
 /**
  * Response from sending feedback.
@@ -340,18 +359,27 @@ interface FeedbackRequest {
  * based on whether the user actually converted.
  */
 interface FeedbackResponse {
-    /** Whether feedback was recorded successfully */
-    success: boolean;
-    /** AI-detected sentiment from user response */
-    sentiment_detected: FeedbackSentiment;
-    /** Potential bonus if prediction is correct (not guaranteed) */
+    /** Status of feedback submission */
+    status: 'received';
+    /** Unique ID for this feedback event */
+    feedback_id: string;
+    /** Potential bonus if prediction is correct (20% for positive, 5% for negative) */
     potential_bonus: string;
-    /** Potential penalty if prediction is wrong */
-    potential_penalty: string;
     /** Explanation of the deferred bonus system */
     message: string;
-    /** When the bonus will be resolved (7 days from now) */
+    /** When the bonus will be resolved (7 days from impression, YYYY-MM-DD) */
     resolution_date: string;
+    /**
+     * AI-detected sentiment (only present in auto-analysis mode).
+     * Shows what sentiment our AI detected from the user response.
+     */
+    sentiment_detected?: 'positive' | 'neutral' | 'negative';
+    /**
+     * Analysis mode used (only present in auto-analysis or fallback modes).
+     * - 'auto': AI analyzed sentiment
+     * - 'fallback': AI failed, defaulted to neutral
+     */
+    analysis_mode?: 'auto' | 'fallback';
 }
 interface PolicyResponse {
     version: string;

package/dist/index.d.ts

@@ -294,44 +294,63 @@ interface EventIngestRequest {
 interface EventIngestResponse {
     accepted: boolean;
 }
-/**
- * Sentiment types detected by backend AI analysis.
- *
- * - positive: User is interested/engaged (earn +15% if converts, -5% if not)
- * - neutral: User is indifferent (no bonus/penalty, data only)
- * - negative: User disliked the ad (no penalty, data only)
- */
-type FeedbackSentiment = 'positive' | 'neutral' | 'negative';
 /**
  * Send feedback on an ad after showing it to a user.
  *
- * **New in v0.11.0:** Backend analyzes sentiment automatically using AI.
- * Just send the user's actual response text - no need to classify it yourself.
+ * **Two modes available:**
  *
- * **Anti-Fraud:** Bonuses are deferred and validated against actual conversions.
- * - Correct positive prediction → +15% bonus after 7 days
- * - Wrong positive prediction → -5% penalty after 7 days
- * - Neutral/negative → no bonus/penalty (data only)
+ * **Auto-Analysis (Recommended):** Send the user's raw response, and our AI analyzes sentiment.
+ * ```typescript
+ * await client.sendFeedback({
+ *   tracking_token: ad.tracking_token,
+ *   user_response: "Tell me more about that!",
+ *   conversation_history: ["Previous message 1", "Previous message 2"]
+ * });
+ * ```
  *
- * @example
+ * **Manual Prediction:** Analyze sentiment yourself and send the prediction.
  * ```typescript
  * await client.sendFeedback({
  *   tracking_token: ad.tracking_token,
- *   user_response: "This looks perfect! How do I sign up?",
- *   agent_response: "Here's the signup link...",
- *   additional_context: "User spent 2 minutes reading the offer"
+ *   reaction: 'positive',  // You determine this
+ *   context: 'User asked follow-up questions'
  * });
  * ```
+ *
+ * **Bonuses (7-day deferred):**
+ * - Correct positive prediction → +20% bonus
+ * - Correct negative prediction → +5% bonus
+ * - Wrong prediction or no feedback → No bonus
  */
 interface FeedbackRequest {
-    /** Tracking token from the ad you showed */
+    /** Tracking token from the ad you showed (required) */
     tracking_token: string;
-    /** User's actual response text (required) */
-    user_response: string;
-    /** Your agent's response (optional, helps sentiment analysis) */
-    agent_response?: string;
-    /** Additional context about the interaction (optional) */
-    additional_context?: string;
+    /**
+     * OPTION 1 (Auto-Analysis): User's actual response text.
+     * Our AI will analyze sentiment and determine positive/neutral/negative.
+     * Max 2000 characters.
+     */
+    user_response?: string;
+    /**
+     * Conversation history for better context in auto-analysis.
+     * We use the last 3 messages to understand the conversation flow.
+     */
+    conversation_history?: string[];
+    /**
+     * OPTION 2 (Manual): Your prediction of user interest.
+     * Use this if you want full control over sentiment classification.
+     */
+    reaction?: 'positive' | 'neutral' | 'negative';
+    /**
+     * Additional context about the interaction (optional, both modes).
+     * Max 1000 characters.
+     */
+    context?: string;
+    /**
+     * Idempotency key for safe retries (optional).
+     * Use the same key if retrying a failed request to avoid duplicate feedback.
+     */
+    idempotency_key?: string;
 }
 /**
  * Response from sending feedback.
@@ -340,18 +359,27 @@ interface FeedbackRequest {
  * based on whether the user actually converted.
  */
 interface FeedbackResponse {
-    /** Whether feedback was recorded successfully */
-    success: boolean;
-    /** AI-detected sentiment from user response */
-    sentiment_detected: FeedbackSentiment;
-    /** Potential bonus if prediction is correct (not guaranteed) */
+    /** Status of feedback submission */
+    status: 'received';
+    /** Unique ID for this feedback event */
+    feedback_id: string;
+    /** Potential bonus if prediction is correct (20% for positive, 5% for negative) */
     potential_bonus: string;
-    /** Potential penalty if prediction is wrong */
-    potential_penalty: string;
     /** Explanation of the deferred bonus system */
     message: string;
-    /** When the bonus will be resolved (7 days from now) */
+    /** When the bonus will be resolved (7 days from impression, YYYY-MM-DD) */
     resolution_date: string;
+    /**
+     * AI-detected sentiment (only present in auto-analysis mode).
+     * Shows what sentiment our AI detected from the user response.
+     */
+    sentiment_detected?: 'positive' | 'neutral' | 'negative';
+    /**
+     * Analysis mode used (only present in auto-analysis or fallback modes).
+     * - 'auto': AI analyzed sentiment
+     * - 'fallback': AI failed, defaulted to neutral
+     */
+    analysis_mode?: 'auto' | 'fallback';
 }
 interface PolicyResponse {
     version: string;

package/dist/index.js

@@ -1393,6 +1393,7 @@ var AttentionMarketClient = class {
       url
     );
   }
+  // TODO: Add getDeveloperMetrics() method when DeveloperMetricsResponse type is defined
 };
 
 // src/mock-client.ts