@adcp/sdk 15.9.5 → 15.9.7

package/dist/lib/core/SingleAgentClient.js

@@ -215,6 +215,56 @@ const RECORDLESS_HMAC_READ_ONLY_TASKS = /* @__PURE__ */ new Set([
 ]);
 const TASK_SCOPED_STATE_LIMIT = 1e4;
 const WEBHOOK_JWKS_RESOLVER_LIMIT = 1024;
+function creativeMatchesProductOption(creative, declaration) {
+  const params = isPlainRecord(declaration.params) ? declaration.params : {};
+  const assets = isPlainRecord(creative.assets) ? creative.assets : {};
+  const slots = Array.isArray(params.slots) ? params.slots : [];
+  if (!slots.every((slot) => {
+    if (!isPlainRecord(slot) || typeof slot.asset_group_id !== "string") return false;
+    const value = assets[slot.asset_group_id];
+    const entries = value === void 0 ? [] : Array.isArray(value) ? value : [value];
+    const minimum = Math.max(typeof slot.min === "number" ? slot.min : 0, slot.required === true ? 1 : 0);
+    if (entries.length < minimum || typeof slot.max === "number" && entries.length > slot.max) return false;
+    return entries.every(
+      (asset) => isPlainRecord(asset) && (typeof slot.asset_type !== "string" || asset.asset_type === slot.asset_type)
+    );
+  }))
+    return false;
+  const formatParams = isPlainRecord(creative.format_parameters) ? creative.format_parameters : {};
+  const kind = String(creative.format_kind);
+  const mediaType = kind.startsWith("image") ? "image" : kind.startsWith("video") ? "video" : kind.startsWith("audio") ? "audio" : kind === "html5" ? "html" : void 0;
+  const assetTypes = mediaType === "video" ? ["video", "vast"] : mediaType === "audio" ? ["audio", "vast", "daast"] : mediaType === "html" ? ["html", "zip"] : mediaType ? [mediaType] : ["image", "video", "audio", "html", "zip", "vast", "daast"];
+  const requiredMediaSlots = slots.filter(
+    (slot) => isPlainRecord(slot) && (slot.required === true || typeof slot.min === "number" && slot.min > 0) && assetTypes.includes(String(slot.asset_type))
+  );
+  const preferredGroups = mediaType ? [`${mediaType}_main`, mediaType, kind, ...assetTypes] : [];
+  const primaryGroup = (requiredMediaSlots.length === 1 ? String(requiredMediaSlots[0].asset_group_id) : void 0) ?? preferredGroups.find((group) => assets[group] !== void 0);
+  const sourceAssets = primaryGroup ? [assets[primaryGroup]] : Object.values(assets);
+  const dimensionalAssets = sourceAssets.flatMap((value) => Array.isArray(value) ? value : [value]).filter(
+    (value) => isPlainRecord(value) && assetTypes.includes(String(value.asset_type))
+  );
+  return (dimensionalAssets.length > 0 ? dimensionalAssets : [{}]).every((asset) => {
+    const actual = { ...asset, ...formatParams };
+    for (const key of ["width", "height"]) {
+      if (typeof params[key] === "number" && actual[key] !== params[key]) return false;
+      const min = params[`min_${key}`];
+      const max = params[`max_${key}`];
+      if (typeof min === "number" && (typeof actual[key] !== "number" || actual[key] < min)) return false;
+      if (typeof max === "number" && (typeof actual[key] !== "number" || actual[key] > max)) return false;
+    }
+    if (Array.isArray(params.sizes) && !params.sizes.some((size) => isPlainRecord(size) && size.width === actual.width && size.height === actual.height))
+      return false;
+    const duration = actual.duration_ms ?? actual.duration_ms_exact;
+    const exact = params.duration_ms_exact ?? params.duration_ms;
+    if (typeof exact === "number" && duration !== exact) return false;
+    if (typeof exact !== "number" && Array.isArray(params.duration_ms_range)) {
+      const [min, max] = params.duration_ms_range;
+      if (typeof duration !== "number" || typeof min === "number" && duration < min || typeof max === "number" && duration > max)
+        return false;
+    }
+    return true;
+  });
+}
 function isDeferredClientFinalizationContext(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const context = value;
@@ -1347,7 +1397,7 @@ class SingleAgentClient {
       }
     }
   }
-  rememberCanonicalProductRoutes(products, account, authoritativeProducts) {
+  rememberCanonicalProductRoutes(products, account, authoritativeProducts, evidence) {
     this.invalidateCanonicalProductRoutes(authoritativeProducts ?? products, account);
     const accountScope = this.canonicalAccountScope(account);
     const declaredOptions = authoritativeProducts ? this.sellerDeclaredFormatOptions(authoritativeProducts) : void 0;
@@ -1367,12 +1417,15 @@ class SingleAgentClient {
         const refs = (0, import_legacy_metadata.legacyFormatRefsForDeclaration)(option);
         const declared = declaredOptions ? declaredOptions.get(product.product_id)?.some((declaredRef) => this.sameCanonicalOptionRef(declaredRef, ref)) : (0, import_legacy_metadata.sellerDeclaredFormatOption)(option);
         if (declared !== void 0) (0, import_legacy_metadata.rememberSellerDeclaredFormatOption)(option, declared);
+        if (declared === true && evidence)
+          (0, import_legacy_metadata.rememberSellerFormatEvidence)(option, { ...evidence, productId: product.product_id });
         this.rememberCanonicalLegacyRoute(this.canonicalLegacyRouteKey(account, product.product_id, ref), {
           kind: "product",
           accountScope,
           productId: product.product_id,
           optionRef: ref,
           refs,
+          ...declared === true && (0, import_legacy_metadata.sellerFormatEvidence)(option) ? { declaration: (0, import_legacy_metadata.structuredCloneWithLegacyCreativeMetadata)(option) } : {},
           ...declared === false ? { undeclaredSelector: (0, import_legacy_routes.undeclaredFormatOptionSelector)(option) } : {}
         });
       }
@@ -4582,6 +4635,13 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         }
       }
       const conditionalSnapshot = skipCacheRead ? void 0 : cache?.read(cacheScope, cacheParams, true);
+      const productEvidence = this.usesScopedDiscoveryTransport(
+        effectiveOptions
+      ) ? void 0 : {
+        scopeKey: this.getCapabilityEvidenceScope().scopeKey,
+        accountScope: this.canonicalAccountScope(account),
+        expiresAt: Date.now() + (0, import_agent_discovery_cache.resolveAgentDiscoveryTtlMs)(this.config.discoveryCache?.ttlMs)
+      };
       const result = await this.executeAndHandle(
         "get_products",
         "onGetProductsStatusChange",
@@ -4594,7 +4654,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
             projectionCatalogs: projectionCatalogs ?? this.config.projectionCatalogs
           });
           const authoritativeProducts = Array.isArray(data.products) ? data.products : response.products;
-          this.rememberCanonicalProductRoutes(response.products, account, authoritativeProducts);
+          this.rememberCanonicalProductRoutes(response.products, account, authoritativeProducts, productEvidence);
           const { _message: _dropLegacyMessage, ...canonical } = response;
           void _dropLegacyMessage;
           return { ...canonical, projection: { diagnostics } };
@@ -4605,7 +4665,9 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       );
       const finishCache = async (completed) => {
         if (!cache) return completed;
-        const cachedResult = cache.write(cacheScope, cacheParams, completed, conditionalSnapshot);
+        const cachedResult = cache.write(cacheScope, cacheParams, completed, conditionalSnapshot, (materialized) => {
+          this.rememberCanonicalProductRoutes(materialized.data?.products ?? [], account, void 0, productEvidence);
+        });
         if (cachedResult.success && cachedResult.status === "completed") {
           if (!skipCacheRead && cacheParams.if_wholesale_feed_version === void 0 && cacheParams.if_pricing_version === void 0 && cachedResult.data.unchanged === true) {
             return this.getProducts(params, inputHandler, {
@@ -4765,7 +4827,12 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     if (hasCreativeFormatData) {
       this.validateBeforeCreativeCapabilityProbe("create_media_buy", params, taskOptions);
     }
-    const wireMode = hasCreativeFormatData ? await this.resolveCreativeFormatWireMode("create_media_buy", taskOptions) : "canonical";
+    const wireMode = hasCreativeFormatData ? await this.resolveCreativeWireMode(
+      "create_media_buy",
+      taskOptions,
+      true,
+      () => this.productOptionsSupportCanonicalWire("create_media_buy", params, [], options)
+    ) : "canonical";
     const wireParams = params;
     const result = await this.executeAndHandle(
       "create_media_buy",
@@ -4853,7 +4920,12 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     if (hasCreativeFormatData) {
       this.validateBeforeCreativeCapabilityProbe("update_media_buy", params, taskOptions);
     }
-    const wireMode = hasCreativeFormatData ? await this.resolveCreativeFormatWireMode("update_media_buy", taskOptions) : "canonical";
+    const wireMode = hasCreativeFormatData ? await this.resolveCreativeWireMode(
+      "update_media_buy",
+      taskOptions,
+      true,
+      () => this.productOptionsSupportCanonicalWire("update_media_buy", params, [], options)
+    ) : "canonical";
     const result = await this.executeAndHandle(
       "update_media_buy",
       "onUpdateMediaBuyStatusChange",
@@ -4942,7 +5014,6 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       projectionCatalogs ?? this.config.projectionCatalogs
     );
     this.validateBeforeCreativeCapabilityProbe("sync_creatives", params, taskOptions);
-    const wireMode = await this.resolveCreativeFormatWireMode("sync_creatives", taskOptions);
     const configuredSelectorContainers = [
       ...creativeFormatProjection?.selectorContainers ?? []
     ];
@@ -4954,10 +5025,17 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     const assignmentPackageContainers = Array.isArray(params.assignments) ? params.assignments.flatMap(
       (assignment) => typeof assignment.package_id === "string" && !configuredPackageIds.has(assignment.package_id) ? [{ package_id: assignment.package_id }] : []
     ) : [];
+    const selectorContainers = [...configuredSelectorContainers, ...assignmentPackageContainers];
+    const wireMode = await this.resolveCreativeWireMode(
+      "sync_creatives",
+      taskOptions,
+      true,
+      () => this.productOptionsSupportCanonicalWire("sync_creatives", params, selectorContainers, options)
+    );
     const wireParams = this.projectUndeclaredFormatOptions(
       (0, import_creative_delivery.projectSyncCreativesForDelivery)(
         params,
-        [...configuredSelectorContainers, ...assignmentPackageContainers],
+        selectorContainers,
         wireMode,
         effectiveLegacyFormatConverter,
         effectiveCanonicalFormatLegacyResolver
@@ -4997,16 +5075,17 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
    * sending a mutation. Discovers capabilities and the current tool's input
    * schema, or reuses fresh cached/primed evidence, with this client's wire pin.
    *
-   * `unknown` preserves the conservative legacy projection for older peers
-   * whose capabilities and schema do not establish support. Projection still
-   * requires an unambiguous legacy reference for each creative in that case.
+   * This context-free check returns `unknown` when capabilities and schema do
+   * not establish support. A write to a proven 3.1 seller can still select
+   * canonical delivery from matching seller-advertised product options;
+   * otherwise projection requires an unambiguous legacy reference.
    * Conflicting evidence and unproven support with a 3.2+ buyer pin throw
    * `CreativeFormatCapabilityError`, just as they do during a write.
    */
   async resolveCreativeFormatWireMode(taskType, options) {
     return this.resolveCreativeWireMode(taskType, options, true);
   }
-  async resolveCreativeWireMode(taskType, options, canRediscover) {
+  async resolveCreativeWireMode(taskType, options, canRediscover, matchingProductOptions) {
     const discoveryContext = {};
     const capabilities = await this.getCapabilities({
       ...options,
@@ -5025,13 +5104,16 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         `Seller capability and ${taskType} input schema disagree about canonical creative support`
       );
     }
-    const resolved = declared !== "unknown" ? declared : schema;
+    let resolved = declared !== "unknown" ? declared : schema;
+    if (resolved === "unknown" && (0, import_creative_delivery.canUseProductOptionsForCreativeWire)(capabilities, wireRelease) && matchingProductOptions?.()) {
+      resolved = "canonical";
+    }
     const release = /^v?(\d+)\.(\d+)(?:\.|-|$)/.exec(wireRelease.trim());
     const canonicalRequiredByBuyerPin = release !== null && (Number(release[1]) > 3 || Number(release[1]) === 3 && Number(release[2]) >= 2);
     if (resolved === "unknown" && canonicalRequiredByBuyerPin) {
       if (canRediscover && !usesScopedFetch && this.normalizedAgent.protocol === "mcp" && this.capabilitiesFromSharedCache && toolSchemas?.has(taskType) && !toolInputSchemasByProperties.has(toolSchemas)) {
         await this.invalidateDiscoveryCache(options);
-        return this.resolveCreativeWireMode(taskType, options, false);
+        return this.resolveCreativeWireMode(taskType, options, false, matchingProductOptions);
       }
       throw new import_creative_delivery.CreativeFormatCapabilityError(
         `Cannot prove which AdCP release the seller serves for ${taskType}; a 3.2+ client will not guess a legacy creative wire shape`
@@ -5039,6 +5121,115 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     }
     return resolved;
   }
+  usesScopedDiscoveryTransport(options) {
+    return (0, import_protocols.normalizeTransportOptions)(options?.transport ?? this.config.transport)?.trustedFetchFn !== void 0;
+  }
+  /** Product evidence applies to this request only; it must never prime a tool-wide capability. */
+  productOptionsSupportCanonicalWire(taskType, request, selectorContainers = [], options) {
+    if (!isPlainRecord(request) || this.usesScopedDiscoveryTransport(options)) return false;
+    const scopeKey = this.getCapabilityEvidenceScope().scopeKey;
+    const accountScope = this.canonicalAccountScope(request.account);
+    const optionRef = (value) => {
+      if (!isPlainRecord(value) || typeof value.format_option_id !== "string" || !value.format_option_id) {
+        return void 0;
+      }
+      if (typeof value.publisher_domain === "string") {
+        return {
+          scope: "publisher",
+          publisher_domain: value.publisher_domain,
+          format_option_id: value.format_option_id
+        };
+      }
+      if (value.scope !== void 0 && value.scope !== "product") return void 0;
+      return { scope: "product", format_option_id: value.format_option_id };
+    };
+    const accepts = (container, creative, depth = 0) => {
+      if (depth > 32) return false;
+      if (Array.isArray(container.selector_containers)) {
+        return container.selector_containers.length > 0 && container.selector_containers.every((nested) => accepts(nested, creative, depth + 1));
+      }
+      const refs = Array.isArray(container.format_option_refs) ? container.format_option_refs.map(optionRef) : [];
+      if (refs.some((ref) => ref === void 0)) return false;
+      const creativeRef = isPlainRecord(creative) ? optionRef(creative.format_option_ref) : void 0;
+      if (isPlainRecord(creative) && creative.format_option_ref !== void 0 && !creativeRef) return false;
+      const isSellerDeclaration = (value) => {
+        if (!isPlainRecord(value) || (0, import_legacy_metadata.sellerDeclaredFormatOption)(value) !== true || (0, import_legacy_metadata.isSynthesizedFormatOption)(value)) {
+          return false;
+        }
+        const evidence2 = (0, import_legacy_metadata.sellerFormatEvidence)(value);
+        if (!evidence2 || evidence2.scopeKey !== scopeKey || typeof container.product_id === "string" && evidence2.productId !== container.product_id || evidence2.expiresAt <= Date.now() || evidence2.accountScope !== accountScope && evidence2.accountScope !== "none")
+          return false;
+        const ref = optionRef(value);
+        if (ref && (0, import_legacy_routes.formatOptionOriginFromRoutes)(
+          options?.canonicalFormatLegacyResolver,
+          ref,
+          typeof container.product_id === "string" ? container.product_id : void 0
+        )?.seller_declared === false)
+          return false;
+        return !ref || typeof container.product_id !== "string" || this.cachedFormatOptionOrigin(request.account, ref, container.product_id)?.seller_declared !== false;
+      };
+      const declarations = [
+        ...(Array.isArray(container.format_options) ? container.format_options : []).filter(isSellerDeclaration),
+        ...(0, import_legacy_metadata.selectedFormatOptions)(container).filter(isSellerDeclaration)
+      ];
+      if (typeof container.product_id === "string") {
+        for (const ref of [...refs, ...creativeRef ? [creativeRef] : []]) {
+          if (!ref) continue;
+          const route = this.routeForOption(request.account, container.product_id, ref);
+          if (route?.kind === "product" && route.declaration && isSellerDeclaration(route.declaration))
+            declarations.push(route.declaration);
+        }
+      }
+      const available = declarations.filter((declaration) => declaration.experimental !== true);
+      const matchesRef = (declaration, ref) => {
+        const declaredRef = optionRef(declaration);
+        return declaredRef !== void 0 && this.sameCanonicalOptionRef(declaredRef, ref);
+      };
+      if (!refs.every((ref) => available.some((declaration) => matchesRef(declaration, ref)))) return false;
+      const selected = available.filter(
+        (declaration) => refs.length === 0 || refs.some((ref) => matchesRef(declaration, ref))
+      );
+      if (creative === void 0) return refs.length > 0 && selected.length > 0;
+      if (!isPlainRecord(creative) || typeof creative.format_kind !== "string" || creative.format_id !== void 0)
+        return false;
+      return selected.some(
+        (declaration) => declaration.format_kind === creative.format_kind && (!creativeRef || matchesRef(declaration, creativeRef)) && creativeMatchesProductOption(creative, declaration)
+      );
+    };
+    if (taskType === "sync_creatives") {
+      if (!Array.isArray(request.creatives) || request.creatives.length === 0) return false;
+      const creatives = request.creatives;
+      const assignments = Array.isArray(request.assignments) ? request.assignments : [];
+      if (!assignments.every(
+        (value) => isPlainRecord(value) && typeof value.package_id === "string" && typeof value.creative_id === "string" && creatives.some((creative) => isPlainRecord(creative) && creative.creative_id === value.creative_id)
+      ))
+        return false;
+      return creatives.every((creative) => {
+        if (!isPlainRecord(creative)) return false;
+        const assigned = new Set(
+          assignments.flatMap(
+            (value) => isPlainRecord(value) && value.creative_id === creative.creative_id && typeof value.package_id === "string" ? [value.package_id] : []
+          )
+        );
+        const relevant = assigned.size === 0 ? selectorContainers : selectorContainers.filter(
+          (container) => typeof container.package_id === "string" && assigned.has(container.package_id)
+        );
+        return relevant.length > 0 && [...assigned].every((id) => relevant.some((container) => container.package_id === id)) && relevant.every((container) => accepts(container, creative));
+      });
+    }
+    const packages = ["packages", "new_packages"].flatMap((key) => Array.isArray(request[key]) ? request[key] : []);
+    let evidence = false;
+    return packages.length > 0 && packages.every((pkg) => {
+      if (!isPlainRecord(pkg)) return false;
+      const creatives = Array.isArray(pkg.creatives) ? pkg.creatives : [];
+      const hasSelectors = Array.isArray(pkg.format_option_refs) && pkg.format_option_refs.length > 0;
+      if (!hasSelectors && creatives.length === 0) {
+        return pkg.format_kind === void 0 && pkg.format_ids === void 0;
+      }
+      evidence = true;
+      return (!hasSelectors || accepts(pkg)) && creatives.every((creative) => accepts(pkg, creative));
+    }) && evidence;
+  }
   /** Validate malformed creative payloads before capability discovery can perform I/O. */
   validateBeforeCreativeCapabilityProbe(taskType, params, options) {
     if (options.skipIdempotencyAutoInject || options.skipAccountValidation || options.skipRequestValidation) return;