@adcp/sdk 12.1.0 → 13.0.0-rc.0

package/dist/lib/core/AgentClient.mjs

@@ -2,7 +2,6 @@ import { randomUUID } from "node:crypto";
 import {
   SingleAgentClient
 } from "./SingleAgentClient.mjs";
-import { withFormatOptions } from "../v2/projection/augment-response.mjs";
 const NON_TERMINAL_STATES = /* @__PURE__ */ new Set([
   "working",
   "input-required",
@@ -202,90 +201,91 @@ class AgentClient {
   verifyWebhookSignature(rawBodyOrPayload, signature, timestamp) {
     return this.client.verifyWebhookSignature(rawBodyOrPayload, signature, timestamp);
   }
+  // ====== MEDIA BUY TASKS ======
+  /**
+   * Discover available advertising products.
+   *
+   * Response products expose only canonical `format_options[]`, regardless of
+   * the seller's negotiated wire version. The SDK performs any required legacy
+   * translation below this public boundary.
+   *
+   * Projection failures surface portably on `result.data.errors[]` and are
+   * also mirrored on `result.data.projection.diagnostics` (structured
+   * `source: 'sdk'` markers; codes mirror the spec's error-code
+   * vocabulary plus three SDK-local codes — see the projection
+   * module's `ProjectionDiagnostic` type for the full set).
+   *
+   * Protocol tooling that must inspect raw seller emission uses the explicit
+   * deprecated `getProductsLegacy()` method.
+   */
   async getProducts(params, inputHandler, options) {
-    const { project, ...sessionOptions } = options ?? {};
     const result = await this.client.getProducts(params, inputHandler, {
-      ...this.withSession("get_products", sessionOptions)
+      ...options,
+      ...this.withSession("get_products", options)
     });
     this.retainSession(result);
-    if (project === false) {
-      return result;
-    }
-    if (result.success && result.status === "completed" && result.data) {
-      const { response, diagnostics } = withFormatOptions(result.data);
-      const augmented = {
-        ...response,
-        projection: { diagnostics }
-      };
-      return {
-        ...result,
-        data: augmented
-      };
-    }
     return result;
   }
-  /**
-   * List available creative formats
-   */
-  async listCreativeFormats(params, inputHandler, options) {
-    const result = await this.client.listCreativeFormats(params, inputHandler, {
+  /** @deprecated Explicit raw-wire escape hatch for migration tooling. */
+  async getProductsLegacy(params, inputHandler, options) {
+    const result = await this.client.getProductsLegacy(params, inputHandler, {
+      ...this.withSession("get_products", options)
+    });
+    this.retainSession(result);
+    return result;
+  }
+  /** @deprecated Migration-only access to a legacy named-format catalog. */
+  async listCreativeFormatsLegacy(params, inputHandler, options) {
+    const result = await this.client.listCreativeFormatsLegacy(params, inputHandler, {
       ...this.withSession("list_creative_formats", options)
     });
     this.retainSession(result);
     return result;
   }
+  /** @deprecated Migration-only access to legacy creative transformer declarations. */
+  async listTransformersLegacy(params, inputHandler, options) {
+    const result = await this.client.listTransformersLegacy(params, inputHandler, {
+      ...this.withSession("list_transformers", options)
+    });
+    this.retainSession(result);
+    return result;
+  }
   /**
    * Create a new media buy.
    *
-   * **3.1+ format-option write flow (preferred at 3.1.0-beta.5+).** After
-   * `getProducts()` returns the V2-augmented response (`format_options[]`
-   * auto-populated), pick declarations by `format_option_id` and use
-   * `packageRefsForFormatOptions` to author the package. The helper emits
-   * BOTH `format_option_refs[]` (the 3.1+ path) AND `format_ids[]`
-   * (legacy named-format dual emission) so a single request works against
-   * both format-option-aware and legacy sellers.
+   * Discover canonical `format_options[]` with `getProducts()`, select a
+   * `format_option_id`, and send only canonical package and creative fields.
+   * Compatibility translation for an older seller happens below this method.
    *
    * ```ts
-   * import { packageRefsForFormatOptions } from '@adcp/sdk/v2/projection';
-   *
    * const { data: { products } } = await agent.getProducts({ brief: '...' });
    * const product = products[0];
+   * const format = product.format_options[0];
    *
    * await agent.createMediaBuy({
    *   packages: [{
    *     package_id: 'pkg-1',
    *     product_id: product.product_id,
    *     pricing_option_id: product.pricing_options[0].pricing_option_id,
-   *     ...packageRefsForFormatOptions(product, ['nytimes_mrec', 'nytimes_video_30s']),
-   *     // ↑ spreads `{ format_option_refs, format_ids? }`
+   *     format_option_refs: [{
+   *       scope: 'product',
+   *       format_option_id: format.format_option_id
+   *     }],
+   *     creatives: [{
+   *       creative_id: 'hero',
+   *       format_kind: format.format_kind,
+   *       format_option_ref: {
+   *         scope: 'product',
+   *         format_option_id: format.format_option_id
+   *       },
+   *       assets: { image: { url: 'https://cdn.example/hero.png' } }
+   *     }],
    *     budget: { currency: 'USD', total: 5000 },
    *   }],
    *   // ...
    * });
    * ```
    *
-   * The resulting wire payload for the package looks like:
-   *
-   * ```json
-   * {
-   *   "package_id": "pkg-1",
-   *   "product_id": "...",
-   *   "pricing_option_id": "...",
-   *   "format_option_refs": [
-   *     {"scope": "product", "format_option_id": "nytimes_mrec"},
-   *     {"scope": "product", "format_option_id": "nytimes_video_30s"}
-   *   ],
-   *   "format_ids": [
-   *     {"agent_url": "https://creative.adcontextprotocol.org/", "id": "display_300x250_image"},
-   *     {"agent_url": "https://creative.adcontextprotocol.org/", "id": "video_standard_30s"}
-   *   ],
-   *   "budget": {"currency": "USD", "total": 5000}
-   * }
-   * ```
-   *
-   * `format_ids` is omitted entirely when every chosen format option is V2-only
-   * (the spec's "neither present" fallback fires for v1 sellers in that case).
-   *
    * **Inline creative fallback.** Sellers that do not advertise a creative
    * library (`supportsSyncCreatives(await agent.getCapabilities()) === false`)
    * can still accept package-scoped creative uploads when they advertise
@@ -296,17 +296,8 @@ class AgentClient {
    * assignments for create payloads, give each package a stable key such as
    * `context.buyer_ref`, or pass a custom `packageId` resolver.
    *
-   * For adopters writing strictly to v1 sellers — or for products whose
-   * `format_options[]` entries don't publish `format_option_id` — see the
-   * `legacyFormatIdsFromOptions` / `tryLegacyFormatIdsFromOptions` /
-   * `legacyFormatIdsForFormatOption` helpers in `@adcp/sdk/v2/projection`.
-   *
-   * `packageRefsForFormatOptions` throws `FormatOptionRefsLookupError`
-   * with a normalized `.code` in `{ 'unknown_format_option_id' |
-   * 'format_option_refs_not_published' | 'empty_input' | 'invalid_product' }`
-   * — branch on `.code` to fall back to the `legacy*` helpers when the
-   * product is V1-shape only. See the helper JSDoc for the full
-   * recovery example.
+   * Existing applications that still hold old named-format payloads must opt
+   * into `createMediaBuyLegacy()` explicitly.
    */
   async createMediaBuy(params, inputHandler, options) {
     const result = await this.client.createMediaBuy(params, inputHandler, {
@@ -315,6 +306,14 @@ class AgentClient {
     this.retainSession(result);
     return result;
   }
+  /** @deprecated Use `createMediaBuy`; this explicit compatibility surface accepts legacy creative `format_id`. */
+  async createMediaBuyLegacy(params, inputHandler, options) {
+    const result = await this.client.createMediaBuyLegacy(params, inputHandler, {
+      ...this.withSession("create_media_buy", options)
+    });
+    this.retainSession(result);
+    return result;
+  }
   /**
    * Update an existing media buy.
    *
@@ -324,6 +323,8 @@ class AgentClient {
    * request. Build the package patch with `inlineCreativesForPackages()` and
    * preflight it with `preflightUpdateMediaBuy(currentBuy, patch)` so
    * `available_actions[]` allows `replace_creative` before dispatch.
+   * Use `format_kind` and `format_option_ref` for every creative in the patch;
+   * the SDK handles any negotiated compatibility conversion.
    */
   async updateMediaBuy(params, inputHandler, options) {
     const result = await this.client.updateMediaBuy(params, inputHandler, {
@@ -332,6 +333,14 @@ class AgentClient {
     this.retainSession(result);
     return result;
   }
+  /** @deprecated Use `updateMediaBuy`; this explicit compatibility surface accepts legacy creative `format_id`. */
+  async updateMediaBuyLegacy(params, inputHandler, options) {
+    const result = await this.client.updateMediaBuyLegacy(params, inputHandler, {
+      ...this.withSession("update_media_buy", options)
+    });
+    this.retainSession(result);
+    return result;
+  }
   /**
    * Sync creative assets into the seller's reusable creative library.
    *
@@ -344,6 +353,11 @@ class AgentClient {
    * send a separate `create_media_buy` or `update_media_buy` request with its
    * own idempotency key. If neither capability is advertised, creative upload
    * is not available through this SDK helper surface.
+   *
+   * A sync request does not carry product declarations. When compatibility
+   * translation needs seller selection metadata, pass
+   * `options.creativeFormatProjection.selectorContainers` with the routed
+   * package/product selectors. Assignments scope each creative to its package.
    */
   async syncCreatives(params, inputHandler, options) {
     const result = await this.client.syncCreatives(params, inputHandler, {
@@ -352,11 +366,32 @@ class AgentClient {
     this.retainSession(result);
     return result;
   }
+  /** @deprecated Use `syncCreatives`; this explicit compatibility surface accepts legacy creative `format_id`. */
+  async syncCreativesLegacy(params, inputHandler, options) {
+    const result = await this.client.syncCreativesLegacy(params, inputHandler, {
+      ...this.withSession("sync_creatives", options)
+    });
+    this.retainSession(result);
+    return result;
+  }
   /**
    * List creative assets
    */
   async listCreatives(params, inputHandler, options) {
     const result = await this.client.listCreatives(params, inputHandler, {
+      ...options,
+      ...this.withSession("list_creatives", options)
+    });
+    this.retainSession(result);
+    return result;
+  }
+  /**
+   * Return the unprojected `list_creatives` wire response.
+   *
+   * @deprecated Compatibility-only escape hatch for migration and protocol tooling.
+   */
+  async listCreativesLegacy(params, inputHandler, options) {
+    const result = await this.client.listCreativesLegacy(params, inputHandler, {
       ...this.withSession("list_creatives", options)
     });
     this.retainSession(result);
@@ -382,6 +417,15 @@ class AgentClient {
     this.retainSession(result);
     return result;
   }
+  /** Retrieve canonical creative-level and variant-level delivery metrics. */
+  async getCreativeDelivery(params, inputHandler, options) {
+    const result = await this.client.getCreativeDelivery(params, inputHandler, {
+      ...options,
+      ...this.withSession("get_creative_delivery", options)
+    });
+    this.retainSession(result);
+    return result;
+  }
   /**
    * Provide performance feedback
    */
@@ -455,21 +499,17 @@ class AgentClient {
   async requireV3(taskType = "request") {
     return this.client.requireSupportedMajor(taskType);
   }
-  /**
-   * Preview a creative
-   */
-  async previewCreative(params, inputHandler, options) {
-    const result = await this.client.previewCreative(params, inputHandler, {
+  /** @deprecated Migration-only access to legacy `format_id`-based creative preview. */
+  async previewCreativeLegacy(params, inputHandler, options) {
+    const result = await this.client.previewCreativeLegacy(params, inputHandler, {
       ...this.withSession("preview_creative", options)
     });
     this.retainSession(result);
     return result;
   }
-  /**
-   * Build a creative from format and brand context
-   */
-  async buildCreative(params, inputHandler, options) {
-    const result = await this.client.buildCreative(params, inputHandler, {
+  /** @deprecated Migration-only access to legacy `target_format_id`-based creative building. */
+  async buildCreativeLegacy(params, inputHandler, options) {
+    const result = await this.client.buildCreativeLegacy(params, inputHandler, {
       ...this.withSession("build_creative", options)
     });
     this.retainSession(result);
@@ -560,8 +600,8 @@ class AgentClient {
   /**
    * List content standards
    */
-  async listContentStandards(params, inputHandler, options) {
-    const result = await this.client.listContentStandards(params, inputHandler, {
+  async listContentStandardsLegacy(params, inputHandler, options) {
+    const result = await this.client.listContentStandardsLegacy(params, inputHandler, {
       ...this.withSession("list_content_standards", options)
     });
     this.retainSession(result);
@@ -570,8 +610,8 @@ class AgentClient {
   /**
    * Get content standards
    */
-  async getContentStandards(params, inputHandler, options) {
-    const result = await this.client.getContentStandards(params, inputHandler, {
+  async getContentStandardsLegacy(params, inputHandler, options) {
+    const result = await this.client.getContentStandardsLegacy(params, inputHandler, {
       ...this.withSession("get_content_standards", options)
     });
     this.retainSession(result);
@@ -580,8 +620,8 @@ class AgentClient {
   /**
    * Calibrate content against standards
    */
-  async calibrateContent(params, inputHandler, options) {
-    const result = await this.client.calibrateContent(params, inputHandler, {
+  async calibrateContentLegacy(params, inputHandler, options) {
+    const result = await this.client.calibrateContentLegacy(params, inputHandler, {
       ...this.withSession("calibrate_content", options)
     });
     this.retainSession(result);
@@ -590,8 +630,8 @@ class AgentClient {
   /**
    * Validate content delivery
    */
-  async validateContentDelivery(params, inputHandler, options) {
-    const result = await this.client.validateContentDelivery(params, inputHandler, {
+  async validateContentDeliveryLegacy(params, inputHandler, options) {
+    const result = await this.client.validateContentDeliveryLegacy(params, inputHandler, {
       ...this.withSession("validate_content_delivery", options)
     });
     this.retainSession(result);
@@ -824,7 +864,56 @@ class AgentClient {
     return this.client.getActiveTasks();
   }
   async executeTask(taskName, params, inputHandler, options) {
-    const result = await this.client.executeTask(taskName, params, inputHandler, {
+    switch (taskName) {
+      case "get_products":
+        return this.getProducts(params, inputHandler, options);
+      case "create_media_buy":
+        return await this.createMediaBuy(
+          params,
+          inputHandler,
+          options
+        );
+      case "update_media_buy":
+        return await this.updateMediaBuy(
+          params,
+          inputHandler,
+          options
+        );
+      case "sync_creatives":
+        return await this.syncCreatives(
+          params,
+          inputHandler,
+          options
+        );
+      case "list_creatives":
+        return this.listCreatives(params, inputHandler, options);
+      case "get_media_buys":
+        return this.getMediaBuys(params, inputHandler, options);
+      case "get_media_buy_delivery":
+        return this.getMediaBuyDelivery(params, inputHandler, options);
+      case "get_creative_delivery":
+        return this.getCreativeDelivery(params, inputHandler, options);
+    }
+    const result = await this.client.executeTaskLegacy(taskName, params, inputHandler, {
+      ...this.withSession(taskName, options)
+    });
+    this.retainSession(result);
+    return result;
+  }
+  /** Execute an extension task that is not part of the standard AdCP task set. */
+  async executeCustomTask(taskName, params, inputHandler, options) {
+    const result = await this.client.executeCustomTask(taskName, params, inputHandler, {
+      ...this.withSession(taskName, options)
+    });
+    this.retainSession(result);
+    return result;
+  }
+  /**
+   * Explicit raw-task compatibility escape hatch for conformance and migration tooling.
+   * @deprecated Application code should use typed primary methods or `executeTask()`.
+   */
+  async executeTaskLegacy(taskName, params, inputHandler, options) {
+    const result = await this.client.executeTaskLegacy(taskName, params, inputHandler, {
       ...this.withSession(taskName, options)
     });
     this.retainSession(result);