@the_ro_show/agent-ads-sdk 0.14.0 → 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

@@ -550,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

@@ -550,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

@@ -597,17 +597,22 @@ var AttentionMarketClient = class {
       ...params.optimizeFor && { optimizeFor: params.optimizeFor }
     };
     const response = await this.decideRaw(request, options);
-    if (response.creative) {
-      try {
-        await this.track({
-          event_id: `evt_${generateUUID()}`,
-          event_type: "impression",
-          occurred_at: (/* @__PURE__ */ new Date()).toISOString(),
-          agent_id: this.agentId,
-          tracking_token: response.tracking_token
-        });
-      } catch (error) {
-        console.warn("[AttentionMarket] Failed to auto-track impression:", error);
+    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,
@@ -620,6 +625,7 @@ var AttentionMarketClient = class {
         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",
@@ -633,7 +639,7 @@ var AttentionMarketClient = class {
       };
       return adResponse2;
     }
-    if (response.status === "no_fill" || !response.units || response.units.length === 0) {
+    if (!response || response.status === "no_fill" || !response.units || response.units.length === 0) {
       return null;
     }
     const adUnit = response.units[0];