@the_ro_show/agent-ads-sdk 0.17.0 → 0.18.0

package/README.md

@@ -495,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,
@@ -515,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