@the_ro_show/agent-ads-sdk 0.13.3 → 0.14.2

package/README.md

@@ -368,6 +368,65 @@ const ad = await client.decideFromContext({
 });
 ```
 
+## Performance Optimization
+
+### Payload Optimization (v0.14.0+)
+
+The SDK automatically uses an optimized minimal payload format that reduces response size by **84%** (from 3.2KB to ~520B) while maintaining all essential functionality including relevance scores. This improves:
+
+- **Network efficiency:** 6x less data transfer
+- **Response speed:** Faster parsing and processing
+- **Mobile performance:** Lower bandwidth usage
+- **Cost savings:** Reduced data transfer costs
+
+#### Response Formats
+
+The SDK supports three response formats:
+
+```typescript
+// Minimal format (default, ~520B) - Essentials + relevance
+const ad = await client.decideFromContext({
+  userMessage: "I need car insurance",
+  response_format: 'minimal'  // Optional, this is the default
+});
+
+// Returns:
+{
+  creative: { title, body, cta },
+  click_url: string,
+  tracking_token: string,
+  advertiser_id: string,
+  payout: number,
+  relevance_score: number  // 0.0-1.0 for frontend filtering
+}
+```
+
+For advanced use cases, you can request more detailed responses:
+
+```typescript
+// Standard format (645B) - Includes disclosure info
+const ad = await client.decide({
+  response_format: 'standard',
+  // ... other params
+});
+
+// Verbose format (3.1KB) - Full response with all metadata
+const ad = await client.decide({
+  response_format: 'verbose',
+  // ... other params
+});
+```
+
+#### 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 |
+
+**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.
+
 ## Advanced Features
 
 ### Multi-Turn Conversations
@@ -497,6 +556,38 @@ Use test API keys (`am_test_...`) for development and testing. Test keys:
 
 Switch to live keys (`am_live_...`) when deploying to production.
 
+## 🤖 Claude Code Integration
+
+Building with Claude Code? We've created ready-to-use prompts for seamless integration.
+
+### Quick Start (One Line)
+
+```
+I want to add AttentionMarket ads to my AI app. Credentials:
+- API Key: am_test_YOUR_KEY
+- Agent ID: agt_YOUR_ID
+Create a simple getRelevantAd(message) function that returns ads only when relevant (score>0.7).
+```
+
+### Full Integration Guide
+
+📖 **[Claude Code Integration Guide](CLAUDE_CODE_INTEGRATION.md)** — Copy-paste prompts for:
+- Natural conversation integration
+- Advanced filtering & brand safety
+- Testing & analytics setup
+- Mobile app integration
+- Common patterns & best practices
+
+### Performance Metrics
+
+| Metric | Expected Performance |
+|--------|---------------------|
+| **CTR** | 5-12% average |
+| **Revenue/Click** | $0.50 - $15.00 |
+| **Fill Rate** | 40-60% |
+| **API Latency** | < 100ms p95 |
+| **Payload Size** | ~520 bytes |
+
 ## Support
 
 - **Documentation:** [docs.attentionmarket.ai](https://docs.attentionmarket.ai)

package/dist/index.d.mts

@@ -25,6 +25,9 @@ interface DecideRequest {
     context?: string;
     /** Detected or inferred user intent for semantic matching (optional) */
     user_intent?: string;
+    /** Response format: 'minimal' | 'standard' | 'verbose' (default: 'minimal') */
+    response_format?: string;
+    [key: string]: any;
 }
 /**
  * Simplified request for semantic context-based ad matching.
@@ -127,11 +130,27 @@ interface DecideFromContextRequest {
     optimizeFor?: 'revenue' | 'relevance';
 }
 interface DecideResponse {
-    request_id: string;
-    decision_id: string;
-    status: 'filled' | 'no_fill';
-    ttl_ms: number;
-    units: AdUnit[];
+    request_id?: string;
+    decision_id?: string;
+    status?: 'filled' | 'no_fill';
+    ttl_ms?: number;
+    units?: AdUnit[];
+    creative?: {
+        title: string;
+        body: string;
+        cta: string;
+    };
+    click_url?: string;
+    tracking_token?: string;
+    advertiser_id?: string;
+    payout?: number;
+    disclosure?: {
+        label: string;
+        explanation: string;
+        sponsor_name: string;
+    };
+    relevance_score?: number;
+    [key: string]: any;
 }
 type PlacementType = 'sponsored_suggestion' | 'sponsored_block' | 'sponsored_tool';
 interface Placement {
@@ -531,6 +550,8 @@ interface AdResponse {
     tracking_url?: string;
     /** Tracking token for event tracking */
     tracking_token: string;
+    /** Relevance score (0.0-1.0) for frontend rendering decisions */
+    relevance_score?: number;
     /** Disclosure information */
     disclosure: Disclosure;
     /** Full ad unit (for advanced usage) */

package/dist/index.d.ts

@@ -25,6 +25,9 @@ interface DecideRequest {
     context?: string;
     /** Detected or inferred user intent for semantic matching (optional) */
     user_intent?: string;
+    /** Response format: 'minimal' | 'standard' | 'verbose' (default: 'minimal') */
+    response_format?: string;
+    [key: string]: any;
 }
 /**
  * Simplified request for semantic context-based ad matching.
@@ -127,11 +130,27 @@ interface DecideFromContextRequest {
     optimizeFor?: 'revenue' | 'relevance';
 }
 interface DecideResponse {
-    request_id: string;
-    decision_id: string;
-    status: 'filled' | 'no_fill';
-    ttl_ms: number;
-    units: AdUnit[];
+    request_id?: string;
+    decision_id?: string;
+    status?: 'filled' | 'no_fill';
+    ttl_ms?: number;
+    units?: AdUnit[];
+    creative?: {
+        title: string;
+        body: string;
+        cta: string;
+    };
+    click_url?: string;
+    tracking_token?: string;
+    advertiser_id?: string;
+    payout?: number;
+    disclosure?: {
+        label: string;
+        explanation: string;
+        sponsor_name: string;
+    };
+    relevance_score?: number;
+    [key: string]: any;
 }
 type PlacementType = 'sponsored_suggestion' | 'sponsored_block' | 'sponsored_tool';
 interface Placement {
@@ -531,6 +550,8 @@ interface AdResponse {
     tracking_url?: string;
     /** Tracking token for event tracking */
     tracking_token: string;
+    /** Relevance score (0.0-1.0) for frontend rendering decisions */
+    relevance_score?: number;
     /** Disclosure information */
     disclosure: Disclosure;
     /** Full ad unit (for advanced usage) */

package/dist/index.js

@@ -468,7 +468,7 @@ var AttentionMarketClient = class {
     if (response.status === "no_fill") {
       return null;
     }
-    return response.units[0] ?? null;
+    return response.units?.[0] ?? null;
   }
   /**
    * Simplified ad matching using conversation context and semantic search.
@@ -584,6 +584,8 @@ var AttentionMarketClient = class {
       },
       context,
       user_intent: params.userMessage,
+      // Use minimal response format by default for better performance
+      response_format: "minimal",
       // Developer controls (Phase 1: Quality & Brand Safety)
       ...params.minQualityScore !== void 0 && { minQualityScore: params.minQualityScore },
       ...params.allowedCategories && { allowedCategories: params.allowedCategories },
@@ -595,7 +597,49 @@ var AttentionMarketClient = class {
       ...params.optimizeFor && { optimizeFor: params.optimizeFor }
     };
     const response = await this.decideRaw(request, options);
-    if (response.status === "no_fill" || response.units.length === 0) {
+    if (response && response.creative) {
+      if (response["_meta"]) {
+        try {
+          await this.track({
+            event_id: `evt_${generateUUID()}`,
+            event_type: "impression",
+            occurred_at: (/* @__PURE__ */ new Date()).toISOString(),
+            agent_id: this.agentId,
+            request_id: response["_meta"]["request_id"],
+            decision_id: response["_meta"]["decision_id"],
+            unit_id: response["_meta"]["unit_id"],
+            tracking_token: response.tracking_token
+          });
+        } catch (error) {
+          console.warn("[AttentionMarket] Failed to auto-track impression:", error);
+        }
+      }
+      const adResponse2 = {
+        request_id: request.request_id,
+        decision_id: `dec_${generateUUID()}`,
+        advertiser_id: response.advertiser_id || "",
+        ad_type: "link",
+        payout: response.payout || 0,
+        creative: response.creative,
+        click_url: response.click_url || "",
+        tracking_url: response.click_url || "",
+        // Same as click_url
+        tracking_token: response.tracking_token || "",
+        ...response.relevance_score !== void 0 && { relevance_score: response.relevance_score },
+        disclosure: response.disclosure || {
+          label: "Sponsored",
+          explanation: "This is a paid advertisement",
+          sponsor_name: "Advertiser"
+        },
+        // Internal fields preserved for backward compatibility
+        _ad: {
+          unit_id: "",
+          tracking: { token: response.tracking_token || "" }
+        }
+      };
+      return adResponse2;
+    }
+    if (!response || response.status === "no_fill" || !response.units || response.units.length === 0) {
       return null;
     }
     const adUnit = response.units[0];
@@ -908,7 +952,7 @@ var AttentionMarketClient = class {
       user_intent: params.intentKey
     };
     const response = await this.decideRaw(request, { idempotencyKey });
-    if (response.status === "no_fill" || response.units.length === 0) {
+    if (response.status === "no_fill" || !response.units || response.units.length === 0) {
       return null;
     }
     const adUnit = response.units[0];
@@ -919,7 +963,7 @@ var AttentionMarketClient = class {
     const matchMethod = semanticContext ? "hybrid" : "semantic";
     return {
       offer_id: adUnit.unit_id,
-      request_id: response.request_id,
+      request_id: response.request_id || "",
       impression_id: impressionId,
       // LIMITATION: Backend doesn't return campaign_id yet - use unit_id as placeholder
       campaign_id: adUnit.unit_id,
@@ -950,7 +994,7 @@ var AttentionMarketClient = class {
           ...params.revenueSharePct !== void 0 ? { source_agent_pct: params.revenueSharePct } : {}
         }
       } : {},
-      ttl_ms: response.ttl_ms
+      ttl_ms: response.ttl_ms || 3e5
     };
   }
   /**
@@ -1041,7 +1085,7 @@ var AttentionMarketClient = class {
       user_intent: params.userMessage
     };
     const response = await this.decideRaw(request, { idempotencyKey });
-    if (response.status === "no_fill" || response.units.length === 0) {
+    if (response.status === "no_fill" || !response.units || response.units.length === 0) {
       return null;
     }
     const adUnit = response.units[0];
@@ -1052,7 +1096,7 @@ var AttentionMarketClient = class {
     const similarity = adUnit._score?.relevance;
     return {
       offer_id: adUnit.unit_id,
-      request_id: response.request_id,
+      request_id: response.request_id || "",
       impression_id: impressionId,
       // LIMITATION: Backend doesn't return campaign_id yet - use unit_id as placeholder
       campaign_id: adUnit.unit_id,
@@ -1083,7 +1127,7 @@ var AttentionMarketClient = class {
           ...params.revenueSharePct !== void 0 ? { source_agent_pct: params.revenueSharePct } : {}
         }
       } : {},
-      ttl_ms: response.ttl_ms
+      ttl_ms: response.ttl_ms || 3e5
     };
   }
   // ============================================================================
@@ -1169,7 +1213,7 @@ var AttentionMarketClient = class {
       user_intent: params.taskDescription
     };
     const response = await this.decideRaw(request);
-    if (response.status === "no_fill" || response.units.length === 0) {
+    if (response.status === "no_fill" || !response.units || response.units.length === 0) {
       return null;
     }
     const adUnit = response.units[0];
@@ -1430,7 +1474,7 @@ var MockAttentionMarketClient = class {
    */
   async decide(request) {
     const response = await this.decideRaw(request);
-    if (response.status === "filled" && response.units.length > 0) {
+    if (response.status === "filled" && response.units && response.units.length > 0) {
       return response.units[0] || null;
     }
     return null;