@adcp/sdk 16.5.0 → 16.6.0

package/dist/lib/v2/projection/creative-delivery.js

@@ -34,6 +34,7 @@ var import_v2_to_v1 = require('./v2-to-v1.js');
 var import_legacy_metadata = require('./legacy-metadata.js');
 var import_jcs = require('../../utils/jcs.js');
 var import_catalog = require('./catalog.js');
+var import_legacy_metadata2 = require('./legacy-metadata.js');
 function stripLegacyCreativeIdentity(value) {
   const legacyTokens = /* @__PURE__ */ new Set();
   const legacyUrlTokens = /* @__PURE__ */ new Set();
@@ -501,16 +502,38 @@ function creativeFormatParameterConstraints(creative) {
   if (width === void 0 && height === void 0 && durationMs === void 0) return void 0;
   return { width, height, durationMs };
 }
-function legacyRefParameterConstraints(ref) {
+function primaryMediaConstraints(creative) {
+  const assetType = creative.format_kind === "image" ? "image" : creative.format_kind === "video_hosted" ? "video" : creative.format_kind === "audio_hosted" ? "audio" : void 0;
+  if (!assetType) return void 0;
+  const assets = Object.values(record(creative.assets) ?? {}).flatMap(
+    (value) => (Array.isArray(value) ? value : [value]).flatMap((item) => {
+      const asset2 = record(item);
+      return asset2?.asset_type === assetType ? [asset2] : [];
+    })
+  );
+  if (assets.length !== 1) return void 0;
+  const asset = assets[0];
+  const width = assetType === "audio" ? void 0 : positiveConstraint(asset.width);
+  const height = assetType === "audio" ? void 0 : positiveConstraint(asset.height);
+  const durationMs = assetType === "image" ? void 0 : positiveConstraint(asset.duration_ms);
+  return width === void 0 && height === void 0 && durationMs === void 0 ? void 0 : { width, height, durationMs };
+}
+function positiveConstraint(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : void 0;
+}
+function legacyRefParameterConstraints(ref, selectorParams) {
   const params = typeof ref.width !== "number" || typeof ref.height !== "number" ? record((0, import_v1_to_v2.canonicalDeclarationFromBareId)(ref.id, { agentUrl: ref.agent_url })?.params) : void 0;
+  const selector = record(selectorParams);
+  const sizes = Array.isArray(selector?.sizes) ? selector.sizes : [];
+  const size = sizes.length === 1 ? record(sizes[0]) : void 0;
   return {
-    width: typeof ref.width === "number" ? ref.width : typeof params?.width === "number" ? params.width : void 0,
-    height: typeof ref.height === "number" ? ref.height : typeof params?.height === "number" ? params.height : void 0,
-    durationMs: ref.duration_ms
+    width: typeof ref.width === "number" ? ref.width : typeof params?.width === "number" ? params.width : positiveConstraint(selector?.width) ?? positiveConstraint(size?.width),
+    height: typeof ref.height === "number" ? ref.height : typeof params?.height === "number" ? params.height : positiveConstraint(selector?.height) ?? positiveConstraint(size?.height),
+    durationMs: ref.duration_ms ?? positiveConstraint(selector?.duration_ms_exact) ?? positiveConstraint(selector?.duration_ms)
   };
 }
-function refContradictsConstraints(ref, constraints) {
-  const refConstraints = legacyRefParameterConstraints(ref);
+function refContradictsConstraints(ref, constraints, selectorParams) {
+  const refConstraints = legacyRefParameterConstraints(ref, selectorParams);
   if (constraints.width !== void 0 && refConstraints.width !== void 0 && refConstraints.width !== constraints.width) {
     return true;
   }
@@ -522,8 +545,8 @@ function refContradictsConstraints(ref, constraints) {
   }
   return false;
 }
-function refPinsConstraints(ref, constraints) {
-  const refConstraints = legacyRefParameterConstraints(ref);
+function refPinsConstraints(ref, constraints, selectorParams) {
+  const refConstraints = legacyRefParameterConstraints(ref, selectorParams);
   if (constraints.width !== void 0 && refConstraints.width === void 0) return false;
   if (constraints.height !== void 0 && refConstraints.height === void 0) return false;
   if (constraints.durationMs !== void 0 && typeof refConstraints.durationMs !== "number") return false;
@@ -535,8 +558,8 @@ function legacyIdPinsDimensions(ref) {
   const params = record(declaration.params) ?? {};
   return typeof params.width === "number" || typeof params.height === "number" || typeof params.duration_ms_exact === "number" || Array.isArray(params.sizes);
 }
-function refConstraintKey(ref) {
-  const constraints = legacyRefParameterConstraints(ref);
+function refConstraintKey(ref, selectorParams) {
+  const constraints = legacyRefParameterConstraints(ref, selectorParams);
   return [
     agentIdentity(ref.agent_url),
     constraints.width ?? "",
@@ -546,14 +569,21 @@ function refConstraintKey(ref) {
 }
 function preferMostConstrainedLegacyCandidates(candidates, creative) {
   let remaining = candidates;
-  const constraints = creativeFormatParameterConstraints(creative);
+  const mediaKind = ["image", "video_hosted", "audio_hosted"].includes(String(creative.format_kind));
+  const constraints = creativeFormatParameterConstraints(creative) ?? (remaining.length > 1 ? primaryMediaConstraints(creative) : void 0);
   if (constraints) {
-    remaining = remaining.filter((candidate) => !refContradictsConstraints(candidate.ref, constraints));
-    const pinned = remaining.filter((candidate) => refPinsConstraints(candidate.ref, constraints));
+    remaining = remaining.filter(
+      (candidate) => !refContradictsConstraints(candidate.ref, constraints, mediaKind ? candidate.selectorParams : void 0)
+    );
+    const pinned = remaining.filter(
+      (candidate) => refPinsConstraints(candidate.ref, constraints, mediaKind ? candidate.selectorParams : void 0)
+    );
     if (pinned.length > 0) remaining = pinned;
   }
   if (remaining.length <= 1) return remaining;
-  const constraintKeys = new Set(remaining.map((candidate) => refConstraintKey(candidate.ref)));
+  const constraintKeys = new Set(
+    remaining.map((candidate) => refConstraintKey(candidate.ref, mediaKind ? candidate.selectorParams : void 0))
+  );
   if (constraintKeys.size !== 1) return remaining;
   const specific = remaining.filter((candidate) => legacyIdPinsDimensions(candidate.ref) === true);
   return specific.length > 0 && specific.length < remaining.length ? specific : remaining;
@@ -592,43 +622,82 @@ function selectLegacyRef(creative, container, canonicalFormatLegacyResolver, ope
   matching = preferMostConstrainedLegacyCandidates(matching, creative);
   return matching.length === 1 ? matching[0].ref : void 0;
 }
+function legacyUrlTrackerSlotMatches(slot, tracker) {
+  return slot.asset_type === "url" && slot.requirements?.url_type === "tracker_pixel" && (slot.asset_id === tracker.assetId || slot.requirements.role === tracker.assetId);
+}
 function projectLegacyAssetKeys(assetsValue, definition) {
+  const unchanged = { assets: assetsValue, drifts: [] };
   const assets = record(assetsValue);
-  if (!assets || !Array.isArray(definition?.assets)) return assetsValue;
+  if (!assets || !Array.isArray(definition?.assets)) return unchanged;
   const slots = definition.assets.filter((slot) => record(slot) !== void 0);
-  if (slots.some((slot) => slot.item_type !== void 0 && slot.item_type !== "individual")) return assetsValue;
+  if (slots.some((slot) => slot.item_type !== void 0 && slot.item_type !== "individual")) return unchanged;
   const declaredIds = new Set(slots.map((slot) => slot.asset_id));
   const availableSlots = slots.filter(
-    (slot) => (slot.item_type === void 0 || slot.item_type === "individual") && typeof slot.asset_id === "string" && slot.asset_id.length > 0 && !Object.hasOwn(assets, slot.asset_id)
+    (slot) => typeof slot.asset_id === "string" && slot.asset_id.length > 0 && !Object.hasOwn(assets, slot.asset_id)
   );
   const targetBySource = /* @__PURE__ */ new Map();
   const sourcesByTarget = /* @__PURE__ */ new Map();
+  const trackersBySource = /* @__PURE__ */ new Map();
   for (const [key, value] of Object.entries(assets)) {
-    if (declaredIds.has(key)) continue;
+    const candidates = (Array.isArray(value) ? value : [value]).map(import_legacy_metadata2.downgradePixelTracker);
+    const trackers = candidates.length > 0 && candidates.every((tracker) => tracker !== void 0) ? candidates : void 0;
+    const trackerSlotMatches = (slot2) => trackers !== void 0 && trackers.every((tracker) => legacyUrlTrackerSlotMatches(slot2, tracker));
+    if (declaredIds.has(key)) {
+      const slot2 = slots.find((slot3) => slot3.asset_id === key);
+      if (trackers && slot2 && trackerSlotMatches(slot2)) trackersBySource.set(key, trackers);
+      continue;
+    }
     const asset = record(value);
-    if (!asset || typeof asset.asset_type !== "string") continue;
-    const matches = availableSlots.filter((slot) => {
-      if (slot.asset_type !== asset.asset_type) return false;
+    if (!trackers && (!asset || typeof asset.asset_type !== "string")) continue;
+    const matches = availableSlots.filter((slot2) => {
+      if (trackerSlotMatches(slot2)) return true;
+      if (!asset || slot2.asset_type !== asset.asset_type) return false;
       if (asset.asset_type === "url") {
-        return typeof asset.url_type === "string" && asset.url_type === slot.requirements?.url_type;
+        return typeof asset.url_type === "string" && asset.url_type === slot2.requirements?.url_type;
       }
       if (asset.asset_type === "pixel_tracker") {
-        return typeof asset.event === "string" && asset.event === slot.event && (asset.event !== "custom" || typeof asset.custom_event_name === "string" && asset.custom_event_name === slot.custom_event_name);
+        return typeof asset.event === "string" && asset.event === slot2.event && (asset.event !== "custom" || typeof asset.custom_event_name === "string" && asset.custom_event_name === slot2.custom_event_name);
       }
       return true;
     });
     if (matches.length !== 1) continue;
-    const target = matches[0].asset_id;
+    const slot = matches[0];
+    const target = slot.asset_id;
     targetBySource.set(key, target);
+    if (trackers && trackerSlotMatches(slot)) trackersBySource.set(key, trackers);
     const sources = sourcesByTarget.get(target) ?? [];
     sources.push(key);
     sourcesByTarget.set(target, sources);
   }
   for (const sources of sourcesByTarget.values()) {
-    if (sources.length > 1) for (const source of sources) targetBySource.delete(source);
+    if (sources.length > 1) {
+      for (const source of sources) {
+        targetBySource.delete(source);
+        trackersBySource.delete(source);
+      }
+    }
   }
-  if (targetBySource.size === 0) return assetsValue;
-  return Object.fromEntries(Object.entries(assets).map(([key, value]) => [targetBySource.get(key) ?? key, value]));
+  if (targetBySource.size === 0 && trackersBySource.size === 0) return unchanged;
+  const drifts = [];
+  for (const [key, trackers] of trackersBySource) {
+    trackers.forEach((tracker, index) => {
+      const path = `assets.${key}${Array.isArray(assets[key]) ? `[${index}]` : ""}`;
+      const drift = (0, import_legacy_metadata2.pixelTrackerDrift)(path, tracker);
+      if (drift) drifts.push(drift);
+    });
+  }
+  return {
+    assets: Object.fromEntries(
+      Object.entries(assets).map(([key, value]) => {
+        const trackers = trackersBySource.get(key);
+        return [
+          targetBySource.get(key) ?? key,
+          trackers ? Array.isArray(value) ? trackers.map((tracker) => tracker.asset) : trackers[0].asset : value
+        ];
+      })
+    ),
+    drifts
+  };
 }
 function projectCreative(creative, formatId, legacyFormatDefinitions) {
   const next = { ...creative };
@@ -640,7 +709,12 @@ function projectCreative(creative, formatId, legacyFormatDefinitions) {
     return ref !== void 0 && sameLegacyIdentity(ref, formatId);
   });
   const definition = supplied?.length ? supplied.length === 1 ? supplied[0] : void 0 : (0, import_catalog.lookupV1Format)(formatId);
-  if (Object.hasOwn(creative, "assets")) next.assets = projectLegacyAssetKeys(creative.assets, definition);
+  if (Object.hasOwn(creative, "assets")) {
+    const projected = projectLegacyAssetKeys(creative.assets, definition);
+    next.assets = projected.assets;
+    (0, import_legacy_metadata.transferLegacyCreativeMetadata)(creative, next);
+    (0, import_legacy_metadata2.rememberCreativeDeliveryDiagnostics)(next, projected.drifts);
+  }
   return next;
 }
 function dedupeLegacyRefs(refs) {
@@ -878,6 +952,7 @@ function projectCreativeForDelivery(creative, selectorContainer, wireMode = "can
   const inputRecord = creative;
   const originalLegacyRef = legacyRef(inputRecord.format_id);
   const creativeRecord = canonicalizeCreative(inputRecord, selectorContainer, operation, legacyFormatConverter);
+  (0, import_legacy_metadata.transferLegacyCreativeMetadata)(inputRecord, creativeRecord);
   if (wireMode === "canonical") return creativeRecord;
   if (originalLegacyRef) {
     const selectedOriginal = selectLegacyRef(inputRecord, selectorContainer, canonicalFormatLegacyResolver, operation);
@@ -949,14 +1024,32 @@ function projectCreativeForDelivery(creative, selectorContainer, wireMode = "can
       throw new CreativeFormatProjectionError(
         operation,
         creativeId,
-        `the seller advertised ${candidates.length} legacy refs for canonical kind ${creativeRecord.format_kind}`
+        `the seller advertised ${candidates.length} legacy refs for canonical kind ${creativeRecord.format_kind}` + (candidates.some((candidate) => legacyIdPinsDimensions(candidate.ref) === true) ? "; set format_parameters.width/height or give the asset one rendered width/height to select one" : "")
       );
     }
-    const reason = pinned ? "the creative is pinned to a format option that names none of the selected seller product legacy format references" : "the selected seller product did not provide one unambiguous legacy format reference";
+    const reason = pinned ? "the creative is pinned to a format option that names none of the selected seller product legacy format references" : describeUnmatchedLegacyCandidates(creativeRecord, allCandidates);
     throw new CreativeFormatProjectionError(operation, creativeId, reason);
   }
   return creative;
 }
+function describeUnmatchedLegacyCandidates(creative, allCandidates) {
+  const generic = "the selected seller product did not provide one unambiguous legacy format reference";
+  const kind = String(creative.format_kind);
+  if (allCandidates.length === 0) return generic;
+  const sameKind = allCandidates.filter((candidate) => candidate.formatKind === kind);
+  if (sameKind.length === 0) {
+    const offered = [
+      ...new Set(allCandidates.flatMap((candidate) => candidate.formatKind ? [candidate.formatKind] : []))
+    ];
+    if (offered.length === 0) return generic;
+    return `the selected seller product offers legacy refs for canonical kind ${offered.join(", ")}, not ${kind}`;
+  }
+  const size = creativeFormatParameterConstraints(creative);
+  if (size?.width !== void 0 && size.height !== void 0) {
+    return `none of the seller's ${sameKind.length} ${kind} legacy refs matches the creative's ${size.width}x${size.height} size`;
+  }
+  return generic;
+}
 function projectMediaBuyCreativesForDelivery(request, wireMode = "canonical", operation = "create_media_buy", legacyFormatConverter, canonicalFormatLegacyResolver, legacyFormatDefinitions) {
   const requestRecord = record(request);
   if (!requestRecord) return request;

package/dist/lib/v2/projection/creative-delivery.mjs

@@ -13,6 +13,11 @@ import {
 } from "./legacy-metadata.mjs";
 import { canonicalize as canonicalizeJson } from "../../utils/jcs.mjs";
 import { lookupV1Format } from "./catalog.mjs";
+import {
+  downgradePixelTracker,
+  pixelTrackerDrift,
+  rememberCreativeDeliveryDiagnostics
+} from "./legacy-metadata.mjs";
 function stripLegacyCreativeIdentity(value) {
   const legacyTokens = /* @__PURE__ */ new Set();
   const legacyUrlTokens = /* @__PURE__ */ new Set();
@@ -480,16 +485,38 @@ function creativeFormatParameterConstraints(creative) {
   if (width === void 0 && height === void 0 && durationMs === void 0) return void 0;
   return { width, height, durationMs };
 }
-function legacyRefParameterConstraints(ref) {
+function primaryMediaConstraints(creative) {
+  const assetType = creative.format_kind === "image" ? "image" : creative.format_kind === "video_hosted" ? "video" : creative.format_kind === "audio_hosted" ? "audio" : void 0;
+  if (!assetType) return void 0;
+  const assets = Object.values(record(creative.assets) ?? {}).flatMap(
+    (value) => (Array.isArray(value) ? value : [value]).flatMap((item) => {
+      const asset2 = record(item);
+      return asset2?.asset_type === assetType ? [asset2] : [];
+    })
+  );
+  if (assets.length !== 1) return void 0;
+  const asset = assets[0];
+  const width = assetType === "audio" ? void 0 : positiveConstraint(asset.width);
+  const height = assetType === "audio" ? void 0 : positiveConstraint(asset.height);
+  const durationMs = assetType === "image" ? void 0 : positiveConstraint(asset.duration_ms);
+  return width === void 0 && height === void 0 && durationMs === void 0 ? void 0 : { width, height, durationMs };
+}
+function positiveConstraint(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : void 0;
+}
+function legacyRefParameterConstraints(ref, selectorParams) {
   const params = typeof ref.width !== "number" || typeof ref.height !== "number" ? record(canonicalDeclarationFromBareId(ref.id, { agentUrl: ref.agent_url })?.params) : void 0;
+  const selector = record(selectorParams);
+  const sizes = Array.isArray(selector?.sizes) ? selector.sizes : [];
+  const size = sizes.length === 1 ? record(sizes[0]) : void 0;
   return {
-    width: typeof ref.width === "number" ? ref.width : typeof params?.width === "number" ? params.width : void 0,
-    height: typeof ref.height === "number" ? ref.height : typeof params?.height === "number" ? params.height : void 0,
-    durationMs: ref.duration_ms
+    width: typeof ref.width === "number" ? ref.width : typeof params?.width === "number" ? params.width : positiveConstraint(selector?.width) ?? positiveConstraint(size?.width),
+    height: typeof ref.height === "number" ? ref.height : typeof params?.height === "number" ? params.height : positiveConstraint(selector?.height) ?? positiveConstraint(size?.height),
+    durationMs: ref.duration_ms ?? positiveConstraint(selector?.duration_ms_exact) ?? positiveConstraint(selector?.duration_ms)
   };
 }
-function refContradictsConstraints(ref, constraints) {
-  const refConstraints = legacyRefParameterConstraints(ref);
+function refContradictsConstraints(ref, constraints, selectorParams) {
+  const refConstraints = legacyRefParameterConstraints(ref, selectorParams);
   if (constraints.width !== void 0 && refConstraints.width !== void 0 && refConstraints.width !== constraints.width) {
     return true;
   }
@@ -501,8 +528,8 @@ function refContradictsConstraints(ref, constraints) {
   }
   return false;
 }
-function refPinsConstraints(ref, constraints) {
-  const refConstraints = legacyRefParameterConstraints(ref);
+function refPinsConstraints(ref, constraints, selectorParams) {
+  const refConstraints = legacyRefParameterConstraints(ref, selectorParams);
   if (constraints.width !== void 0 && refConstraints.width === void 0) return false;
   if (constraints.height !== void 0 && refConstraints.height === void 0) return false;
   if (constraints.durationMs !== void 0 && typeof refConstraints.durationMs !== "number") return false;
@@ -514,8 +541,8 @@ function legacyIdPinsDimensions(ref) {
   const params = record(declaration.params) ?? {};
   return typeof params.width === "number" || typeof params.height === "number" || typeof params.duration_ms_exact === "number" || Array.isArray(params.sizes);
 }
-function refConstraintKey(ref) {
-  const constraints = legacyRefParameterConstraints(ref);
+function refConstraintKey(ref, selectorParams) {
+  const constraints = legacyRefParameterConstraints(ref, selectorParams);
   return [
     agentIdentity(ref.agent_url),
     constraints.width ?? "",
@@ -525,14 +552,21 @@ function refConstraintKey(ref) {
 }
 function preferMostConstrainedLegacyCandidates(candidates, creative) {
   let remaining = candidates;
-  const constraints = creativeFormatParameterConstraints(creative);
+  const mediaKind = ["image", "video_hosted", "audio_hosted"].includes(String(creative.format_kind));
+  const constraints = creativeFormatParameterConstraints(creative) ?? (remaining.length > 1 ? primaryMediaConstraints(creative) : void 0);
   if (constraints) {
-    remaining = remaining.filter((candidate) => !refContradictsConstraints(candidate.ref, constraints));
-    const pinned = remaining.filter((candidate) => refPinsConstraints(candidate.ref, constraints));
+    remaining = remaining.filter(
+      (candidate) => !refContradictsConstraints(candidate.ref, constraints, mediaKind ? candidate.selectorParams : void 0)
+    );
+    const pinned = remaining.filter(
+      (candidate) => refPinsConstraints(candidate.ref, constraints, mediaKind ? candidate.selectorParams : void 0)
+    );
     if (pinned.length > 0) remaining = pinned;
   }
   if (remaining.length <= 1) return remaining;
-  const constraintKeys = new Set(remaining.map((candidate) => refConstraintKey(candidate.ref)));
+  const constraintKeys = new Set(
+    remaining.map((candidate) => refConstraintKey(candidate.ref, mediaKind ? candidate.selectorParams : void 0))
+  );
   if (constraintKeys.size !== 1) return remaining;
   const specific = remaining.filter((candidate) => legacyIdPinsDimensions(candidate.ref) === true);
   return specific.length > 0 && specific.length < remaining.length ? specific : remaining;
@@ -571,43 +605,82 @@ function selectLegacyRef(creative, container, canonicalFormatLegacyResolver, ope
   matching = preferMostConstrainedLegacyCandidates(matching, creative);
   return matching.length === 1 ? matching[0].ref : void 0;
 }
+function legacyUrlTrackerSlotMatches(slot, tracker) {
+  return slot.asset_type === "url" && slot.requirements?.url_type === "tracker_pixel" && (slot.asset_id === tracker.assetId || slot.requirements.role === tracker.assetId);
+}
 function projectLegacyAssetKeys(assetsValue, definition) {
+  const unchanged = { assets: assetsValue, drifts: [] };
   const assets = record(assetsValue);
-  if (!assets || !Array.isArray(definition?.assets)) return assetsValue;
+  if (!assets || !Array.isArray(definition?.assets)) return unchanged;
   const slots = definition.assets.filter((slot) => record(slot) !== void 0);
-  if (slots.some((slot) => slot.item_type !== void 0 && slot.item_type !== "individual")) return assetsValue;
+  if (slots.some((slot) => slot.item_type !== void 0 && slot.item_type !== "individual")) return unchanged;
   const declaredIds = new Set(slots.map((slot) => slot.asset_id));
   const availableSlots = slots.filter(
-    (slot) => (slot.item_type === void 0 || slot.item_type === "individual") && typeof slot.asset_id === "string" && slot.asset_id.length > 0 && !Object.hasOwn(assets, slot.asset_id)
+    (slot) => typeof slot.asset_id === "string" && slot.asset_id.length > 0 && !Object.hasOwn(assets, slot.asset_id)
   );
   const targetBySource = /* @__PURE__ */ new Map();
   const sourcesByTarget = /* @__PURE__ */ new Map();
+  const trackersBySource = /* @__PURE__ */ new Map();
   for (const [key, value] of Object.entries(assets)) {
-    if (declaredIds.has(key)) continue;
+    const candidates = (Array.isArray(value) ? value : [value]).map(downgradePixelTracker);
+    const trackers = candidates.length > 0 && candidates.every((tracker) => tracker !== void 0) ? candidates : void 0;
+    const trackerSlotMatches = (slot2) => trackers !== void 0 && trackers.every((tracker) => legacyUrlTrackerSlotMatches(slot2, tracker));
+    if (declaredIds.has(key)) {
+      const slot2 = slots.find((slot3) => slot3.asset_id === key);
+      if (trackers && slot2 && trackerSlotMatches(slot2)) trackersBySource.set(key, trackers);
+      continue;
+    }
     const asset = record(value);
-    if (!asset || typeof asset.asset_type !== "string") continue;
-    const matches = availableSlots.filter((slot) => {
-      if (slot.asset_type !== asset.asset_type) return false;
+    if (!trackers && (!asset || typeof asset.asset_type !== "string")) continue;
+    const matches = availableSlots.filter((slot2) => {
+      if (trackerSlotMatches(slot2)) return true;
+      if (!asset || slot2.asset_type !== asset.asset_type) return false;
       if (asset.asset_type === "url") {
-        return typeof asset.url_type === "string" && asset.url_type === slot.requirements?.url_type;
+        return typeof asset.url_type === "string" && asset.url_type === slot2.requirements?.url_type;
       }
       if (asset.asset_type === "pixel_tracker") {
-        return typeof asset.event === "string" && asset.event === slot.event && (asset.event !== "custom" || typeof asset.custom_event_name === "string" && asset.custom_event_name === slot.custom_event_name);
+        return typeof asset.event === "string" && asset.event === slot2.event && (asset.event !== "custom" || typeof asset.custom_event_name === "string" && asset.custom_event_name === slot2.custom_event_name);
       }
       return true;
     });
     if (matches.length !== 1) continue;
-    const target = matches[0].asset_id;
+    const slot = matches[0];
+    const target = slot.asset_id;
     targetBySource.set(key, target);
+    if (trackers && trackerSlotMatches(slot)) trackersBySource.set(key, trackers);
     const sources = sourcesByTarget.get(target) ?? [];
     sources.push(key);
     sourcesByTarget.set(target, sources);
   }
   for (const sources of sourcesByTarget.values()) {
-    if (sources.length > 1) for (const source of sources) targetBySource.delete(source);
+    if (sources.length > 1) {
+      for (const source of sources) {
+        targetBySource.delete(source);
+        trackersBySource.delete(source);
+      }
+    }
+  }
+  if (targetBySource.size === 0 && trackersBySource.size === 0) return unchanged;
+  const drifts = [];
+  for (const [key, trackers] of trackersBySource) {
+    trackers.forEach((tracker, index) => {
+      const path = `assets.${key}${Array.isArray(assets[key]) ? `[${index}]` : ""}`;
+      const drift = pixelTrackerDrift(path, tracker);
+      if (drift) drifts.push(drift);
+    });
   }
-  if (targetBySource.size === 0) return assetsValue;
-  return Object.fromEntries(Object.entries(assets).map(([key, value]) => [targetBySource.get(key) ?? key, value]));
+  return {
+    assets: Object.fromEntries(
+      Object.entries(assets).map(([key, value]) => {
+        const trackers = trackersBySource.get(key);
+        return [
+          targetBySource.get(key) ?? key,
+          trackers ? Array.isArray(value) ? trackers.map((tracker) => tracker.asset) : trackers[0].asset : value
+        ];
+      })
+    ),
+    drifts
+  };
 }
 function projectCreative(creative, formatId, legacyFormatDefinitions) {
   const next = { ...creative };
@@ -619,7 +692,12 @@ function projectCreative(creative, formatId, legacyFormatDefinitions) {
     return ref !== void 0 && sameLegacyIdentity(ref, formatId);
   });
   const definition = supplied?.length ? supplied.length === 1 ? supplied[0] : void 0 : lookupV1Format(formatId);
-  if (Object.hasOwn(creative, "assets")) next.assets = projectLegacyAssetKeys(creative.assets, definition);
+  if (Object.hasOwn(creative, "assets")) {
+    const projected = projectLegacyAssetKeys(creative.assets, definition);
+    next.assets = projected.assets;
+    transferLegacyCreativeMetadata(creative, next);
+    rememberCreativeDeliveryDiagnostics(next, projected.drifts);
+  }
   return next;
 }
 function dedupeLegacyRefs(refs) {
@@ -857,6 +935,7 @@ function projectCreativeForDelivery(creative, selectorContainer, wireMode = "can
   const inputRecord = creative;
   const originalLegacyRef = legacyRef(inputRecord.format_id);
   const creativeRecord = canonicalizeCreative(inputRecord, selectorContainer, operation, legacyFormatConverter);
+  transferLegacyCreativeMetadata(inputRecord, creativeRecord);
   if (wireMode === "canonical") return creativeRecord;
   if (originalLegacyRef) {
     const selectedOriginal = selectLegacyRef(inputRecord, selectorContainer, canonicalFormatLegacyResolver, operation);
@@ -928,14 +1007,32 @@ function projectCreativeForDelivery(creative, selectorContainer, wireMode = "can
       throw new CreativeFormatProjectionError(
         operation,
         creativeId,
-        `the seller advertised ${candidates.length} legacy refs for canonical kind ${creativeRecord.format_kind}`
+        `the seller advertised ${candidates.length} legacy refs for canonical kind ${creativeRecord.format_kind}` + (candidates.some((candidate) => legacyIdPinsDimensions(candidate.ref) === true) ? "; set format_parameters.width/height or give the asset one rendered width/height to select one" : "")
       );
     }
-    const reason = pinned ? "the creative is pinned to a format option that names none of the selected seller product legacy format references" : "the selected seller product did not provide one unambiguous legacy format reference";
+    const reason = pinned ? "the creative is pinned to a format option that names none of the selected seller product legacy format references" : describeUnmatchedLegacyCandidates(creativeRecord, allCandidates);
     throw new CreativeFormatProjectionError(operation, creativeId, reason);
   }
   return creative;
 }
+function describeUnmatchedLegacyCandidates(creative, allCandidates) {
+  const generic = "the selected seller product did not provide one unambiguous legacy format reference";
+  const kind = String(creative.format_kind);
+  if (allCandidates.length === 0) return generic;
+  const sameKind = allCandidates.filter((candidate) => candidate.formatKind === kind);
+  if (sameKind.length === 0) {
+    const offered = [
+      ...new Set(allCandidates.flatMap((candidate) => candidate.formatKind ? [candidate.formatKind] : []))
+    ];
+    if (offered.length === 0) return generic;
+    return `the selected seller product offers legacy refs for canonical kind ${offered.join(", ")}, not ${kind}`;
+  }
+  const size = creativeFormatParameterConstraints(creative);
+  if (size?.width !== void 0 && size.height !== void 0) {
+    return `none of the seller's ${sameKind.length} ${kind} legacy refs matches the creative's ${size.width}x${size.height} size`;
+  }
+  return generic;
+}
 function projectMediaBuyCreativesForDelivery(request, wireMode = "canonical", operation = "create_media_buy", legacyFormatConverter, canonicalFormatLegacyResolver, legacyFormatDefinitions) {
   const requestRecord = record(request);
   if (!requestRecord) return request;

package/dist/lib/v2/projection/index.d.mts

@@ -47,6 +47,7 @@ export { canonicalFormatLegacyResolverFromRoutes, carryFormatOptionOrigins, lega
 export { augmentProductWithFormatOptions, withFormatOptions, toCanonicalFormatOptionsWithRoutes, toAdditiveCanonicalProduct, withAdditiveCanonicalFormatOptions, toCanonicalOnlyProduct, toCanonicalOnlyResponse, type V2AugmentedProduct, type AdditiveCanonicalProduct, type CanonicalOnlyProduct, } from './augment-response.mjs';
 export { CanonicalFormat, audioDaastFormatDeclaration, audioHostedFormatDeclaration, audioVastFormatDeclaration, agentPlacementFormatDeclaration, canonicalFormatDeclaration, customFormatDeclaration, displayTagFormatDeclaration, legacyFormatRef, legacyFormatRefs, html5FormatDeclaration, imageCarouselFormatDeclaration, imageFormatDeclaration, nativeInFeedFormatDeclaration, productCard, productCardDetailed, responsiveCreativeFormatDeclaration, sellerRenderedStatefulDisplayFormatDeclaration, sponsoredPlacementFormatDeclaration, coordinatedPlacementsFormatDeclaration, videoHostedFormatDeclaration, videoVastFormatDeclaration, type CanonicalFormatDeclaration, type CanonicalFormatDeclarationFields, type CanonicalFormatKind, type CanonicalFormatParams, type FormatReferenceInput, type ProductCardDetailedFields, type ProductCardFields, } from './builders.mjs';
 export { packageRefsForFormatOptions, packageRefsForCapabilities, legacyFormatIdsFromOptions, tryLegacyFormatIdsFromOptions, legacyFormatIdsForFormatOption, legacyFormatIdsForCapability, lintPackageFormatSelectorDimensions, FormatOptionRefsLookupError, CapabilityIdsLookupError, type PackageFormatRefs, type PackageCapabilityRefs, type FormatOptionRef, type FormatOptionSelector, type FormatOptionRefsLookupErrorCode, type CapabilityIdsLookupErrorCode, type PackageFormatSelectorInput, type PackageFormatSelectorDimensionOptions, type FixedSizeDimensions, type PackageFormatSelectorDimensionDiagnosticCode, type PackageFormatSelectorDimensionDiagnostic, } from './write-side.mjs';
+export { getCreativeDeliveryDiagnostics } from './legacy-metadata.mjs';
 export type { V1FormatId, V2ProductFormatDeclaration, V2ProductInput, V2Product, V1ProductInput, V1Product, ProjectionProductInput, ProjectionDiagnostic, } from './types.mjs';
 export { isProjectionProductInput } from './types.mjs';
 export { legacyFormatConverterFromCatalogSnapshots, canonicalFormatLegacyResolverFromCatalogSnapshots, projectionAdaptersFromCatalogSnapshots, type ProjectionCatalogAdapters, type ProjectionCatalogSnapshot, type ProjectionCatalogSource, } from './catalog-snapshot.mjs';

package/dist/lib/v2/projection/index.d.ts

@@ -47,6 +47,7 @@ export { canonicalFormatLegacyResolverFromRoutes, carryFormatOptionOrigins, lega
 export { augmentProductWithFormatOptions, withFormatOptions, toCanonicalFormatOptionsWithRoutes, toAdditiveCanonicalProduct, withAdditiveCanonicalFormatOptions, toCanonicalOnlyProduct, toCanonicalOnlyResponse, type V2AugmentedProduct, type AdditiveCanonicalProduct, type CanonicalOnlyProduct, } from './augment-response';
 export { CanonicalFormat, audioDaastFormatDeclaration, audioHostedFormatDeclaration, audioVastFormatDeclaration, agentPlacementFormatDeclaration, canonicalFormatDeclaration, customFormatDeclaration, displayTagFormatDeclaration, legacyFormatRef, legacyFormatRefs, html5FormatDeclaration, imageCarouselFormatDeclaration, imageFormatDeclaration, nativeInFeedFormatDeclaration, productCard, productCardDetailed, responsiveCreativeFormatDeclaration, sellerRenderedStatefulDisplayFormatDeclaration, sponsoredPlacementFormatDeclaration, coordinatedPlacementsFormatDeclaration, videoHostedFormatDeclaration, videoVastFormatDeclaration, type CanonicalFormatDeclaration, type CanonicalFormatDeclarationFields, type CanonicalFormatKind, type CanonicalFormatParams, type FormatReferenceInput, type ProductCardDetailedFields, type ProductCardFields, } from './builders';
 export { packageRefsForFormatOptions, packageRefsForCapabilities, legacyFormatIdsFromOptions, tryLegacyFormatIdsFromOptions, legacyFormatIdsForFormatOption, legacyFormatIdsForCapability, lintPackageFormatSelectorDimensions, FormatOptionRefsLookupError, CapabilityIdsLookupError, type PackageFormatRefs, type PackageCapabilityRefs, type FormatOptionRef, type FormatOptionSelector, type FormatOptionRefsLookupErrorCode, type CapabilityIdsLookupErrorCode, type PackageFormatSelectorInput, type PackageFormatSelectorDimensionOptions, type FixedSizeDimensions, type PackageFormatSelectorDimensionDiagnosticCode, type PackageFormatSelectorDimensionDiagnostic, } from './write-side';
+export { getCreativeDeliveryDiagnostics } from './legacy-metadata';
 export type { V1FormatId, V2ProductFormatDeclaration, V2ProductInput, V2Product, V1ProductInput, V1Product, ProjectionProductInput, ProjectionDiagnostic, } from './types';
 export { isProjectionProductInput } from './types';
 export { legacyFormatConverterFromCatalogSnapshots, canonicalFormatLegacyResolverFromCatalogSnapshots, projectionAdaptersFromCatalogSnapshots, type ProjectionCatalogAdapters, type ProjectionCatalogSnapshot, type ProjectionCatalogSource, } from './catalog-snapshot';

package/dist/lib/v2/projection/index.js

@@ -38,6 +38,7 @@ __export(projection_exports, {
   customFormatDeclaration: () => import_builders.customFormatDeclaration,
   displayTagFormatDeclaration: () => import_builders.displayTagFormatDeclaration,
   findCatalogEntryByCanonicalAndSize: () => import_catalog.findCatalogEntryByCanonicalAndSize,
+  getCreativeDeliveryDiagnostics: () => import_legacy_metadata.getCreativeDeliveryDiagnostics,
   html5FormatDeclaration: () => import_builders.html5FormatDeclaration,
   imageCarouselFormatDeclaration: () => import_builders.imageCarouselFormatDeclaration,
   imageFormatDeclaration: () => import_builders.imageFormatDeclaration,
@@ -89,6 +90,7 @@ var import_legacy_routes = require('./legacy-routes.js');
 var import_augment_response = require('./augment-response.js');
 var import_builders = require('./builders.js');
 var import_write_side = require('./write-side.js');
+var import_legacy_metadata = require('./legacy-metadata.js');
 var import_types = require('./types.js');
 var import_catalog_snapshot = require('./catalog-snapshot.js');
 var import_catalog = require('./catalog.js');
@@ -117,6 +119,7 @@ var import_creative_delivery = require('./creative-delivery.js');
   customFormatDeclaration,
   displayTagFormatDeclaration,
   findCatalogEntryByCanonicalAndSize,
+  getCreativeDeliveryDiagnostics,
   html5FormatDeclaration,
   imageCarouselFormatDeclaration,
   imageFormatDeclaration,

package/dist/lib/v2/projection/index.mjs

@@ -49,6 +49,7 @@ import {
   FormatOptionRefsLookupError,
   CapabilityIdsLookupError
 } from "./write-side.mjs";
+import { getCreativeDeliveryDiagnostics } from "./legacy-metadata.mjs";
 import { isProjectionProductInput } from "./types.mjs";
 import {
   legacyFormatConverterFromCatalogSnapshots,
@@ -94,6 +95,7 @@ export {
   customFormatDeclaration,
   displayTagFormatDeclaration,
   findCatalogEntryByCanonicalAndSize,
+  getCreativeDeliveryDiagnostics,
   html5FormatDeclaration,
   imageCarouselFormatDeclaration,
   imageFormatDeclaration,

package/dist/lib/v2/projection/legacy-metadata.d.mts

@@ -1,5 +1,24 @@
 import type { ProductFormatDeclaration } from '../../types/tools.generated.mjs';
 import type { V1FormatId, V2ProductFormatDeclaration } from './types.mjs';
+import type { VersionDrift } from '../../adapters/version/types.mjs';
+type Json = Record<string, unknown>;
+export interface LegacyPixelTracker {
+    asset: Json;
+    assetId: string;
+    lostFields: string[];
+}
+/** Apply the AdCP 3.1 pixel-tracker schema's normative 3.0 downgrade table. */
+export declare function downgradePixelTracker(value: unknown): LegacyPixelTracker | undefined;
+export declare function pixelTrackerDrift(path: string, tracker: LegacyPixelTracker): VersionDrift | undefined;
+/** Keep delivery advisories out of creative JSON sent to the seller. */
+export declare function rememberCreativeDeliveryDiagnostics(value: object, entries: readonly VersionDrift[]): void;
+export declare function transferCreativeDeliveryDiagnostics(source: object, target: object): void;
+/**
+ * Read advisories from a projected creative or a sync/create/update request.
+ * Pure projection callers can surface these alongside the returned wire object.
+ * SingleAgentClient includes them in the task's debug logs automatically.
+ */
+export declare function getCreativeDeliveryDiagnostics(value: unknown): VersionDrift[];
 /**
  * SDK-private projection metadata held out-of-band. WeakMaps keep seller
  * origin evidence and legacy routing identifiers absent from canonical objects

package/dist/lib/v2/projection/legacy-metadata.d.ts

@@ -1,5 +1,24 @@
 import type { ProductFormatDeclaration } from '../../types/tools.generated';
 import type { V1FormatId, V2ProductFormatDeclaration } from './types';
+import type { VersionDrift } from '../../adapters/version/types';
+type Json = Record<string, unknown>;
+export interface LegacyPixelTracker {
+    asset: Json;
+    assetId: string;
+    lostFields: string[];
+}
+/** Apply the AdCP 3.1 pixel-tracker schema's normative 3.0 downgrade table. */
+export declare function downgradePixelTracker(value: unknown): LegacyPixelTracker | undefined;
+export declare function pixelTrackerDrift(path: string, tracker: LegacyPixelTracker): VersionDrift | undefined;
+/** Keep delivery advisories out of creative JSON sent to the seller. */
+export declare function rememberCreativeDeliveryDiagnostics(value: object, entries: readonly VersionDrift[]): void;
+export declare function transferCreativeDeliveryDiagnostics(source: object, target: object): void;
+/**
+ * Read advisories from a projected creative or a sync/create/update request.
+ * Pure projection callers can surface these alongside the returned wire object.
+ * SingleAgentClient includes them in the task's debug logs automatically.
+ */
+export declare function getCreativeDeliveryDiagnostics(value: unknown): VersionDrift[];
 /**
  * SDK-private projection metadata held out-of-band. WeakMaps keep seller
  * origin evidence and legacy routing identifiers absent from canonical objects