@the_ro_show/agent-ads-sdk 0.16.1 → 0.17.1

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.
 
@@ -466,16 +495,16 @@ The SDK automatically uses an optimized minimal payload format that reduces resp
 
 #### Response Formats
 
-The SDK supports three response formats:
+The SDK supports three response formats that control both detail level and the number of ads returned:
 
 ```typescript
-// Minimal format (default, ~520B) - Essentials + relevance
+// Minimal format (default) - 1 ad, essentials + relevance
 const ad = await client.decideFromContext({
   userMessage: "I need car insurance",
   response_format: 'minimal'  // Optional, this is the default
 });
 
-// Returns:
+// Returns a single ad object:
 {
   creative: { title, body, cta },
   click_url: string,
@@ -486,31 +515,47 @@ const ad = await client.decideFromContext({
 }
 ```
 
-For advanced use cases, you can request more detailed responses:
+For multi-ad or detailed responses, use the `standard` or `verbose` formats:
 
 ```typescript
-// Standard format (645B) - Includes disclosure info
-const ad = await client.decide({
+// Standard format — up to 3 ads, includes disclosure info
+const result = await client.decide({
   response_format: 'standard',
   // ... other params
 });
 
-// Verbose format (3.1KB) - Full response with all metadata
-const ad = await client.decide({
+// Response wraps ads in an `ads` array:
+// { ads: [{ creative, click_url, tracking_token, payout, disclosure, ... }] }
+result.ads.forEach(ad => {
+  console.log(`${ad.creative.title} (relevance: ${ad.relevance_score})`);
+});
+```
+
+```typescript
+// Verbose format — up to 10 ads, adds auction + category metadata
+const debug = await client.decide({
   response_format: 'verbose',
   // ... other params
 });
+
+// Response wraps ads in a `units` array:
+// { units: [{ ...all standard fields, campaign_id, auction_clearing_price, matched_categories }] }
+debug.units.forEach(unit => {
+  console.log(`${unit.creative.title} — clearing price: ${unit.auction_clearing_price}`);
+});
 ```
 
+> **Tip:** All formats may return fewer ads than the maximum if fewer qualify after auction filtering. Always iterate the array rather than assuming a fixed count.
+
 #### Format Comparison
 
-| Format | Size | Use Case | Auto-impression |
-|--------|------|----------|-----------------|
-| **minimal** | ~520B | Production apps (default, includes relevance) | ✅ Yes |
-| **standard** | ~645B | Apps needing disclosure details | ❌ Manual |
-| **verbose** | ~3.1KB | Debugging, analytics | ❌ Manual |
+| Format | Max Ads | Response Key | Size | Best For | Auto-impression |
+|--------|---------|-------------|------|----------|-----------------|
+| **minimal** | 1 | `ad` (object) | ~520B | Production apps (default) | ✅ Yes |
+| **standard** | 3 | `ads` (array) | ~645B/ad | Showing multiple options, disclosure compliance | ❌ Manual |
+| **verbose** | 10 | `units` (array) | ~3.1KB/ad | Debugging, analytics, auction inspection | ❌ Manual |
 
-**Note:** The minimal format automatically tracks impressions for you. When using standard or verbose formats with the raw `decide()` API, you must manually track impressions.
+**Note:** The minimal format automatically tracks impressions. When using standard or verbose formats with the raw `decide()` API, you must track impressions manually.
 
 ## Advanced Features
 
@@ -586,6 +631,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 +865,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,57 @@ 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';
+}
+/**
+ * Rate the delivery quality of an ad after a verified click.
+ *
+ * @example
+ * ```typescript
+ * await client.rateBusinessDelivery({
+ *   tracking_token: ad.tracking_token,
+ *   ad_unit_id: ad._ad.unit_id,
+ *   rating: 4,
+ *   context: 'Relevant product, good landing page'
+ * });
+ * ```
+ */
+interface BusinessRatingRequest {
+    /** Tracking token from the ad (required) */
+    tracking_token: string;
+    /** Ad unit ID from the ad response (required) */
+    ad_unit_id: string;
+    /** Delivery quality rating: 1 (poor) to 5 (excellent) */
+    rating: 1 | 2 | 3 | 4 | 5;
+    /** Optional context about the rating (max 500 chars) */
+    context?: string;
+    /** Idempotency key for safe retries (optional) */
+    idempotency_key?: string;
+}
+interface BusinessRatingResponse {
+    status: 'received';
+    rating_id: string;
+    campaign_id: string;
 }
 interface PolicyResponse {
     version: string;
@@ -932,6 +990,22 @@ declare class AttentionMarketClient {
      * ```
      */
     sendFeedback(request: FeedbackRequest): Promise<FeedbackResponse>;
+    /**
+     * Rate the delivery quality of an ad after a verified click.
+     * Requires a prior click event for the tracking_token. Ratings feed
+     * into quality scores (minimum 5 unique raters per campaign).
+     *
+     * @example
+     * ```typescript
+     * await client.rateBusinessDelivery({
+     *   tracking_token: ad.tracking_token,
+     *   ad_unit_id: ad._ad.unit_id,
+     *   rating: 4,
+     *   context: 'Relevant product, good landing page'
+     * });
+     * ```
+     */
+    rateBusinessDelivery(request: BusinessRatingRequest): Promise<BusinessRatingResponse>;
     /**
      * Fetch default policy constraints and formatting requirements.
      */

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,57 @@ 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';
+}
+/**
+ * Rate the delivery quality of an ad after a verified click.
+ *
+ * @example
+ * ```typescript
+ * await client.rateBusinessDelivery({
+ *   tracking_token: ad.tracking_token,
+ *   ad_unit_id: ad._ad.unit_id,
+ *   rating: 4,
+ *   context: 'Relevant product, good landing page'
+ * });
+ * ```
+ */
+interface BusinessRatingRequest {
+    /** Tracking token from the ad (required) */
+    tracking_token: string;
+    /** Ad unit ID from the ad response (required) */
+    ad_unit_id: string;
+    /** Delivery quality rating: 1 (poor) to 5 (excellent) */
+    rating: 1 | 2 | 3 | 4 | 5;
+    /** Optional context about the rating (max 500 chars) */
+    context?: string;
+    /** Idempotency key for safe retries (optional) */
+    idempotency_key?: string;
+}
+interface BusinessRatingResponse {
+    status: 'received';
+    rating_id: string;
+    campaign_id: string;
 }
 interface PolicyResponse {
     version: string;
@@ -932,6 +990,22 @@ declare class AttentionMarketClient {
      * ```
      */
     sendFeedback(request: FeedbackRequest): Promise<FeedbackResponse>;
+    /**
+     * Rate the delivery quality of an ad after a verified click.
+     * Requires a prior click event for the tracking_token. Ratings feed
+     * into quality scores (minimum 5 unique raters per campaign).
+     *
+     * @example
+     * ```typescript
+     * await client.rateBusinessDelivery({
+     *   tracking_token: ad.tracking_token,
+     *   ad_unit_id: ad._ad.unit_id,
+     *   rating: 4,
+     *   context: 'Relevant product, good landing page'
+     * });
+     * ```
+     */
+    rateBusinessDelivery(request: BusinessRatingRequest): Promise<BusinessRatingResponse>;
     /**
      * Fetch default policy constraints and formatting requirements.
      */

package/dist/index.js

@@ -865,6 +865,24 @@ var AttentionMarketClient = class {
   async sendFeedback(request) {
     return await this.http.request("POST", "/feedback", { body: request });
   }
+  /**
+   * Rate the delivery quality of an ad after a verified click.
+   * Requires a prior click event for the tracking_token. Ratings feed
+   * into quality scores (minimum 5 unique raters per campaign).
+   *
+   * @example
+   * ```typescript
+   * await client.rateBusinessDelivery({
+   *   tracking_token: ad.tracking_token,
+   *   ad_unit_id: ad._ad.unit_id,
+   *   rating: 4,
+   *   context: 'Relevant product, good landing page'
+   * });
+   * ```
+   */
+  async rateBusinessDelivery(request) {
+    return await this.http.request("POST", "/rate-business", { body: request });
+  }
   /**
    * Fetch default policy constraints and formatting requirements.
    */
@@ -1393,6 +1411,7 @@ var AttentionMarketClient = class {
       url
     );
   }
+  // TODO: Add getDeveloperMetrics() method when DeveloperMetricsResponse type is defined
 };
 
 // src/mock-client.ts