@the_ro_show/agent-ads-sdk 0.17.0 → 0.17.1

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
 

package/dist/index.d.mts

@@ -381,6 +381,36 @@ interface FeedbackResponse {
      */
     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;
     disclosure: {
@@ -960,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

@@ -381,6 +381,36 @@ interface FeedbackResponse {
      */
     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;
     disclosure: {
@@ -960,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.
    */