@adcp/sdk 12.1.1 → 13.0.0-rc.0

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

@@ -0,0 +1,967 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var creative_delivery_exports = {};
+__export(creative_delivery_exports, {
+  CreativeFormatCapabilityError: () => CreativeFormatCapabilityError,
+  CreativeFormatProjectionError: () => CreativeFormatProjectionError,
+  projectCreativeForDelivery: () => projectCreativeForDelivery,
+  projectMediaBuyCreativesForDelivery: () => projectMediaBuyCreativesForDelivery,
+  projectSyncCreativesForDelivery: () => projectSyncCreativesForDelivery,
+  resolveCreativeFormatWireMode: () => resolveCreativeFormatWireMode,
+  stripLegacyCreativeIdentity: () => stripLegacyCreativeIdentity
+});
+module.exports = __toCommonJS(creative_delivery_exports);
+var import_v1_to_v2 = require('./v1-to-v2.js');
+var import_v2_to_v1 = require('./v2-to-v1.js');
+var import_legacy_metadata = require('./legacy-metadata.js');
+function stripLegacyCreativeIdentity(value) {
+  const legacyTokens = /* @__PURE__ */ new Set();
+  const legacyUrlTokens = /* @__PURE__ */ new Set();
+  const canonicalKinds = /* @__PURE__ */ new Set([
+    "image",
+    "html5",
+    "display_tag",
+    "image_carousel",
+    "video_hosted",
+    "video_vast",
+    "audio_hosted",
+    "audio_daast",
+    "sponsored_placement",
+    "native_in_feed",
+    "responsive_creative",
+    "agent_placement",
+    "custom"
+  ]);
+  const creativeIdentityKey = (key) => key === "_message" || /(^|_)(?:format_ids?|v1_format_ref)($|_)/.test(key);
+  const ownDataValue = (owner, key) => {
+    const descriptor = Object.getOwnPropertyDescriptor(owner, key);
+    return descriptor && "value" in descriptor ? descriptor.value : void 0;
+  };
+  const nonCreativeAgentContext = (key) => typeof key === "string" && !/(^|_)(?:creative|format|legacy)($|_)/.test(key) && /(^|_)(?:agents?|agent_details|agent_info)($|_)/.test(key);
+  const nonCreativeSignalContext = (owner, key) => ownDataValue(owner, "source") === "agent" && typeof key === "string" && /(^|_)signal_ids?($|_)/.test(key);
+  const nonCreativeListContext = (owner, key) => typeof ownDataValue(owner, "list_id") === "string" && typeof key === "string" && /(^|_)(?:property_list|collection_list|list_ref)($|_)/.test(key);
+  const explicitNonCreativeContextKey = (key) => nonCreativeAgentContext(key) || typeof key === "string" && /(^|_)(?:signal_ids?|property_list|collection_list|list_ref)($|_)/.test(key);
+  const standaloneLegacyTuple = (owner, ownerKey) => {
+    if (nonCreativeAgentContext(ownerKey) || nonCreativeSignalContext(owner, ownerKey) || nonCreativeListContext(owner, ownerKey)) {
+      return false;
+    }
+    if (typeof ownDataValue(owner, "agent_url") !== "string" || typeof ownDataValue(owner, "id") !== "string") {
+      return false;
+    }
+    return true;
+  };
+  const preservesNonCreativeAgentUrl = (key, owner, ownerKey) => {
+    if (!/(^|_)agent_url($|_)/.test(key)) return false;
+    if (key === "agent_url") {
+      return nonCreativeAgentContext(ownerKey) || nonCreativeSignalContext(owner, ownerKey) || nonCreativeListContext(owner, ownerKey) || typeof ownDataValue(owner, "id") === "string" && !standaloneLegacyTuple(owner, ownerKey);
+    }
+    return !/(^|_)(?:creative|format|legacy|offending|target|input|output)($|_)/.test(key);
+  };
+  const legacyKey = (key, owner, ownerKey) => {
+    if (creativeIdentityKey(key)) return true;
+    if (!/(^|_)agent_url($|_)/.test(key)) return false;
+    if (preservesNonCreativeAgentUrl(key, owner, ownerKey)) return false;
+    const value2 = ownDataValue(owner, key);
+    return typeof value2 === "string" && legacyTokens.has(value2);
+  };
+  const collectStrings = (current, seen = /* @__PURE__ */ new WeakSet(), ownerKey) => {
+    if (typeof current === "string") {
+      if (current.length > 1) {
+        legacyTokens.add(current);
+        if (ownerKey === "agent_url" || /^https?:\/\//i.test(current)) legacyUrlTokens.add(current);
+      }
+      return;
+    }
+    if (current === null || typeof current !== "object" || seen.has(current)) return;
+    seen.add(current);
+    if (Array.isArray(current)) {
+      for (const child of current) collectStrings(child, seen, ownerKey);
+      return;
+    }
+    for (const key of Reflect.ownKeys(current)) {
+      const descriptor = Object.getOwnPropertyDescriptor(current, key);
+      if (!descriptor || !("value" in descriptor)) continue;
+      collectStrings(descriptor.value, seen, typeof key === "string" ? key : ownerKey);
+    }
+  };
+  const tokenSeenByContext = {
+    default: /* @__PURE__ */ new WeakSet(),
+    nonCreativeAgent: /* @__PURE__ */ new WeakSet()
+  };
+  const collectLegacyTokens = (current, ownerKey) => {
+    const seen = explicitNonCreativeContextKey(ownerKey) ? tokenSeenByContext.nonCreativeAgent : tokenSeenByContext.default;
+    if (current === null || typeof current !== "object" || seen.has(current)) return;
+    seen.add(current);
+    if (Array.isArray(current)) {
+      for (const child of current) collectLegacyTokens(child, ownerKey);
+      return;
+    }
+    const owner = current;
+    if (standaloneLegacyTuple(owner, ownerKey)) collectStrings(owner, /* @__PURE__ */ new WeakSet(), ownerKey);
+    for (const key of Object.getOwnPropertyNames(owner)) {
+      const descriptor = Object.getOwnPropertyDescriptor(owner, key);
+      if (!descriptor || !("value" in descriptor)) continue;
+      const child = descriptor.value;
+      if (creativeIdentityKey(key)) collectStrings(child);
+      else collectLegacyTokens(child, key);
+    }
+  };
+  collectLegacyTokens(value);
+  const sanitizeText = (text, ownerKey) => {
+    const mentionsLegacyIdentity = /\b(?:format_id|format_ids|target_format_ids|input_format_ids|output_format_ids|v1_format_ref|agent_url)\b/.test(
+      text
+    );
+    let safe = text;
+    if (mentionsLegacyIdentity) {
+      safe = safe.replace(/\bhttps?:\/\/[^\s"'`<>]+/g, "[legacy creative identity]");
+      safe = safe.replace(
+        /(\b(?:format_ids?|v1_format_ref|agent_url)\b(?:\s+(?:was|is|from))?\s*[:=]?\s*["'`]?)\b[a-zA-Z0-9][a-zA-Z0-9_.-]{1,}/g,
+        "$1[legacy creative identity]"
+      );
+    }
+    safe = safe.replace(
+      /\b(?:format_id|format_ids|target_format_ids|input_format_ids|output_format_ids|v1_format_ref|agent_url)\b/g,
+      "legacy creative identity"
+    );
+    for (const token of [...legacyUrlTokens].sort((left, right) => right.length - left.length)) {
+      safe = safe.split(token).join("[legacy creative identity]");
+    }
+    const diagnosticContext = mentionsLegacyIdentity || typeof ownerKey === "string" && /(^|_)(?:message|question|prompt|error|reason|summary|context|stack|diagnostic)($|_)/.test(ownerKey);
+    if (diagnosticContext) {
+      for (const token of [...legacyTokens].sort((left, right) => right.length - left.length)) {
+        if (legacyUrlTokens.has(token) || canonicalKinds.has(token)) continue;
+        if (token.length < 8 && !/[_:/. -]/.test(token)) continue;
+        safe = safe.split(token).join("[legacy creative identity]");
+      }
+    }
+    return safe;
+  };
+  const seenByContext = {
+    default: /* @__PURE__ */ new WeakMap(),
+    nonCreativeAgent: /* @__PURE__ */ new WeakMap()
+  };
+  const hasCustomToJSON = (candidate) => {
+    let cursor = candidate;
+    while (cursor) {
+      const descriptor = Object.getOwnPropertyDescriptor(cursor, "toJSON");
+      if (descriptor) return !("value" in descriptor) || typeof descriptor.value === "function";
+      cursor = Object.getPrototypeOf(cursor);
+    }
+    return false;
+  };
+  const strip = (current, ownerKey) => {
+    if (typeof current === "string") return sanitizeText(current, ownerKey);
+    if (current === null || typeof current !== "object") return current;
+    const seen = explicitNonCreativeContextKey(ownerKey) ? seenByContext.nonCreativeAgent : seenByContext.default;
+    const cached = seen.get(current);
+    if (cached !== void 0) return cached;
+    if (Array.isArray(current)) {
+      const result2 = [];
+      seen.set(current, result2);
+      const needsSafeToJSON2 = hasCustomToJSON(current);
+      let changed2 = needsSafeToJSON2 || Object.getPrototypeOf(current) !== Array.prototype;
+      for (const key of Reflect.ownKeys(current)) {
+        if (key === "length") continue;
+        const descriptor = Object.getOwnPropertyDescriptor(current, key);
+        if (!descriptor) continue;
+        if (!("value" in descriptor)) {
+          changed2 = true;
+          continue;
+        }
+        if (key === "toJSON" && typeof descriptor.value === "function") {
+          changed2 = true;
+          continue;
+        }
+        if (typeof key === "string" && legacyKey(key, current, ownerKey)) {
+          changed2 = true;
+          continue;
+        }
+        const safe = strip(descriptor.value, typeof key === "string" && !/^\d+$/.test(key) ? key : ownerKey);
+        if (safe !== descriptor.value) changed2 = true;
+        Object.defineProperty(result2, key, { ...descriptor, value: safe });
+      }
+      result2.length = current.length;
+      if (!changed2) {
+        seen.set(current, current);
+        return current;
+      }
+      if (needsSafeToJSON2) {
+        Object.defineProperty(result2, "toJSON", {
+          configurable: true,
+          enumerable: false,
+          value: () => Array.from(result2)
+        });
+      }
+      (0, import_legacy_metadata.transferLegacyCreativeMetadata)(current, result2);
+      return result2;
+    }
+    const prototype = Object.getPrototypeOf(current);
+    const plain = prototype === Object.prototype || prototype === null;
+    const safePrototype = prototype === null ? null : Error.prototype.isPrototypeOf(current) ? Error.prototype : Object.prototype;
+    const result = Object.create(safePrototype);
+    seen.set(current, result);
+    const owner = current;
+    if (standaloneLegacyTuple(owner, ownerKey)) {
+      const empty = {};
+      seen.set(current, empty);
+      return empty;
+    }
+    const needsSafeToJSON = hasCustomToJSON(current);
+    let changed = !plain || needsSafeToJSON;
+    const keys = Reflect.ownKeys(current);
+    for (const key of keys) {
+      const descriptor = Object.getOwnPropertyDescriptor(current, key);
+      if (!descriptor) continue;
+      if (!("value" in descriptor)) {
+        changed = true;
+        continue;
+      }
+      const child = descriptor.value;
+      if (typeof key === "symbol") {
+        const safe2 = strip(child);
+        if (safe2 !== child) changed = true;
+        if (!plain) Object.defineProperty(result, key, { ...descriptor, value: safe2 });
+        continue;
+      }
+      if (key === "toJSON" && typeof child === "function") {
+        changed = true;
+        continue;
+      }
+      if (legacyKey(key, owner, ownerKey)) {
+        changed = true;
+        continue;
+      }
+      const safe = preservesNonCreativeAgentUrl(key, owner, ownerKey) ? child : strip(child, key);
+      if (safe !== child) changed = true;
+      if (plain && typeof key === "string" && descriptor.enumerable) result[key] = safe;
+      else Object.defineProperty(result, key, { ...descriptor, value: safe });
+    }
+    if (!changed) {
+      seen.set(current, current);
+      return current;
+    }
+    if (needsSafeToJSON) {
+      Object.defineProperty(result, "toJSON", {
+        configurable: true,
+        enumerable: false,
+        value: () => {
+          const serialized = {};
+          for (const key of Object.keys(result)) serialized[key] = result[key];
+          return serialized;
+        }
+      });
+    }
+    (0, import_legacy_metadata.transferLegacyCreativeMetadata)(current, result);
+    return result;
+  };
+  return strip(value);
+}
+class CreativeFormatProjectionError extends Error {
+  constructor(operation, creativeId, reason) {
+    super(`${operation}: cannot select a valid creative wire shape for ${creativeId}: ${reason}`);
+    this.operation = operation;
+    this.creativeId = creativeId;
+    this.name = "CreativeFormatProjectionError";
+  }
+  operation;
+  creativeId;
+  code = "ADCP_CREATIVE_FORMAT_PROJECTION_FAILED";
+}
+class CreativeFormatCapabilityError extends Error {
+  code = "ADCP_CREATIVE_FORMAT_CAPABILITY_CONTRADICTION";
+  constructor(message) {
+    super(message);
+    this.name = "CreativeFormatCapabilityError";
+  }
+}
+const CANONICAL_FORMAT_KINDS = /* @__PURE__ */ new Set([
+  "image",
+  "html5",
+  "display_tag",
+  "image_carousel",
+  "video_hosted",
+  "video_vast",
+  "audio_hosted",
+  "audio_daast",
+  "sponsored_placement",
+  "native_in_feed",
+  "responsive_creative",
+  "agent_placement",
+  "custom"
+]);
+function record(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function legacyRef(value) {
+  const candidate = record(value);
+  if (!candidate || typeof candidate.agent_url !== "string" || typeof candidate.id !== "string") return void 0;
+  if (candidate.agent_url.length === 0 || candidate.id.length === 0) return void 0;
+  return {
+    agent_url: candidate.agent_url,
+    id: candidate.id,
+    ...typeof candidate.width === "number" ? { width: candidate.width } : {},
+    ...typeof candidate.height === "number" ? { height: candidate.height } : {},
+    ...typeof candidate.duration_ms === "number" ? { duration_ms: candidate.duration_ms } : {}
+  };
+}
+function refsFromValue(value) {
+  if (Array.isArray(value)) return value.flatMap((item) => refsFromValue(item));
+  const ref = legacyRef(value);
+  return ref ? [ref] : [];
+}
+function optionReference(value) {
+  const option = record(value);
+  if (!option || typeof option.format_option_id !== "string" || option.format_option_id.length === 0) return void 0;
+  const canonicalOnly = option.canonical_formats_only === true ? { canonical_formats_only: true } : {};
+  if (typeof option.publisher_domain === "string") {
+    return {
+      scope: "publisher",
+      publisher_domain: option.publisher_domain,
+      format_option_id: option.format_option_id,
+      ...canonicalOnly
+    };
+  }
+  return { scope: "product", format_option_id: option.format_option_id, ...canonicalOnly };
+}
+function sameOptionReference(left, right) {
+  return left.scope === right.scope && left.format_option_id === right.format_option_id && (left.scope !== "publisher" || right.scope === "publisher" && left.publisher_domain === right.publisher_domain);
+}
+function selectedOptionReferences(container) {
+  const direct = Array.isArray(container.format_option_refs) ? container.format_option_refs.flatMap((value) => {
+    const ref = optionReference(value);
+    return ref ? [ref] : [];
+  }) : [];
+  const nested = Array.isArray(container.selector_containers) ? container.selector_containers.flatMap(selectedOptionReferences) : [];
+  return [...direct, ...nested];
+}
+function agentIdentity(value) {
+  try {
+    return new URL(value).href;
+  } catch {
+    return value;
+  }
+}
+function sameLegacyIdentity(left, right) {
+  return agentIdentity(left.agent_url) === agentIdentity(right.agent_url) && left.id === right.id;
+}
+function candidatesFromContainer(container, canonicalFormatLegacyResolver, operation = "creative_delivery") {
+  if (Array.isArray(container.selector_containers)) {
+    return uniqueCandidates(
+      container.selector_containers.flatMap(
+        (candidate) => candidatesFromContainer(candidate, canonicalFormatLegacyResolver, operation)
+      )
+    );
+  }
+  const candidates = [];
+  const containerKind = typeof container.format_kind === "string" ? container.format_kind : void 0;
+  for (const key of ["format_ids", "formats"]) {
+    for (const ref of refsFromValue(container[key])) {
+      candidates.push({
+        ref,
+        formatKind: (0, import_v1_to_v2.resolveCanonicalFormatKind)(ref.id) ?? containerKind,
+        selectorParams: container.params
+      });
+    }
+  }
+  const formatOptions = [
+    ...Array.isArray(container.format_options) ? container.format_options : [],
+    ...(0, import_legacy_metadata.selectedFormatOptions)(container)
+  ];
+  for (const optionValue of formatOptions) {
+    const option = record(optionValue);
+    if (!option) continue;
+    const formatKind = typeof option.format_kind === "string" ? option.format_kind : void 0;
+    const formatOptionRef = optionReference(option);
+    let refs = [...(0, import_legacy_metadata.legacyFormatRefsForDeclaration)(option)];
+    if (refs.length === 0 && option.canonical_formats_only !== true && formatKind) {
+      try {
+        refs = (0, import_v2_to_v1.resolveCanonicalFormatLegacyRefs)(canonicalFormatLegacyResolver, {
+          source: "product",
+          declaration: option,
+          productId: typeof container.product_id === "string" ? container.product_id : "<selector>",
+          field: formatOptionRef?.format_option_id ?? "(format option)"
+        }) ?? [];
+      } catch (error) {
+        if (!(error instanceof import_v2_to_v1.CanonicalFormatLegacyResolutionError)) throw error;
+        throw new CreativeFormatProjectionError(
+          operation,
+          "(format option)",
+          "canonical format legacy resolver returned an invalid product mapping"
+        );
+      }
+    }
+    for (const ref of refs) {
+      candidates.push({ ref, formatKind, formatOptionRef, selectorParams: option.params ?? container.params });
+    }
+  }
+  return uniqueCandidates(candidates);
+}
+function containerOptsOutOfLegacy(container, formatKind, formatOptionRef) {
+  if (formatOptionRef?.canonical_formats_only === true) return true;
+  if (Array.isArray(container.selector_containers) && container.selector_containers.some((candidate) => containerOptsOutOfLegacy(candidate, formatKind, formatOptionRef))) {
+    return true;
+  }
+  const selectedRefs = selectedOptionReferences(container);
+  if (selectedRefs.some((ref) => {
+    if (ref.canonical_formats_only !== true) return false;
+    return formatOptionRef === void 0 || sameOptionReference(ref, formatOptionRef);
+  })) {
+    return true;
+  }
+  const formatOptions = [
+    ...Array.isArray(container.format_options) ? container.format_options : [],
+    ...(0, import_legacy_metadata.selectedFormatOptions)(container)
+  ];
+  return formatOptions.some((value) => {
+    const option = record(value);
+    if (!option || option.canonical_formats_only !== true) return false;
+    if (formatKind && option.format_kind !== formatKind) return false;
+    if (formatOptionRef) {
+      const optionRef = optionReference(option);
+      if (!optionRef || !sameOptionReference(optionRef, formatOptionRef)) return false;
+    }
+    return true;
+  });
+}
+function candidateKey(candidate) {
+  const ref = candidate.ref;
+  return [
+    agentIdentity(ref.agent_url),
+    ref.id,
+    ref.width ?? "",
+    ref.height ?? "",
+    ref.duration_ms ?? "",
+    candidate.formatOptionRef?.scope ?? "",
+    candidate.formatOptionRef?.format_option_id ?? "",
+    candidate.formatOptionRef?.scope === "publisher" ? candidate.formatOptionRef.publisher_domain : ""
+  ].join("|");
+}
+function uniqueCandidates(candidates) {
+  return [...new Map(candidates.map((candidate) => [candidateKey(candidate), candidate])).values()];
+}
+function refMatchesParams(ref, paramsValue) {
+  const params = record(paramsValue);
+  if (!params) return true;
+  const sizes = Array.isArray(params.sizes) ? params.sizes.flatMap((size) => record(size) ? [record(size)] : []) : [];
+  if (sizes.length === 1) {
+    const size = sizes[0];
+    if (typeof size.width === "number" && ref.width !== size.width) return false;
+    if (typeof size.height === "number" && ref.height !== size.height) return false;
+  }
+  if (typeof params.width === "number" && ref.width !== params.width) return false;
+  if (typeof params.height === "number" && ref.height !== params.height) return false;
+  if (typeof params.duration_ms_exact === "number" && ref.duration_ms !== params.duration_ms_exact) return false;
+  return true;
+}
+function selectLegacyRef(creative, container, canonicalFormatLegacyResolver, operation = "creative_delivery") {
+  let candidates = candidatesFromContainer(container, canonicalFormatLegacyResolver, operation);
+  const creativeOptionRef = optionReference(creative.format_option_ref);
+  const selectedOptionRefs = Array.isArray(container.format_option_refs) ? container.format_option_refs.flatMap((value) => {
+    const ref = optionReference(value);
+    return ref ? [ref] : [];
+  }) : [];
+  if (creativeOptionRef) {
+    if (selectedOptionRefs.length > 0 && !selectedOptionRefs.some((ref) => sameOptionReference(ref, creativeOptionRef))) {
+      return void 0;
+    }
+    candidates = candidates.filter(
+      (candidate) => candidate.formatOptionRef && sameOptionReference(candidate.formatOptionRef, creativeOptionRef)
+    );
+  } else if (selectedOptionRefs.length > 0) {
+    candidates = candidates.filter(
+      (candidate) => candidate.formatOptionRef && selectedOptionRefs.some((ref) => sameOptionReference(ref, candidate.formatOptionRef))
+    );
+  }
+  const existing = legacyRef(creative.format_id);
+  if (existing) {
+    const exact = candidates.filter(
+      (candidate) => sameLegacyIdentity(candidate.ref, existing) && (existing.width === void 0 || candidate.ref.width === existing.width) && (existing.height === void 0 || candidate.ref.height === existing.height) && (existing.duration_ms === void 0 || candidate.ref.duration_ms === existing.duration_ms)
+    );
+    if (exact.length === 1) return exact[0].ref;
+    return candidates.length === 0 ? existing : void 0;
+  }
+  if (typeof creative.format_kind !== "string") return void 0;
+  let matching = candidates.filter((candidate) => candidate.formatKind === creative.format_kind);
+  const constrained = matching.filter((candidate) => refMatchesParams(candidate.ref, candidate.selectorParams));
+  if (constrained.length > 0) matching = constrained;
+  return matching.length === 1 ? matching[0].ref : void 0;
+}
+function projectCreative(creative, formatId) {
+  const next = { ...creative };
+  delete next.format_kind;
+  delete next.format_option_ref;
+  next.format_id = { ...formatId };
+  return next;
+}
+function dedupeLegacyRefs(refs) {
+  return [...new Map(refs.map((ref) => [candidateKey({ ref }), { ...ref }])).values()];
+}
+function projectPackageSelectors(pkg, wireMode, operation, legacyFormatConverter, canonicalFormatLegacyResolver) {
+  const next = { ...pkg };
+  const optionRefs = Array.isArray(pkg.format_option_refs) ? pkg.format_option_refs.flatMap((value) => {
+    const ref = optionReference(value);
+    return ref ? [ref] : [];
+  }) : [];
+  const legacyRefs = refsFromValue(pkg.format_ids);
+  const candidates = candidatesFromContainer(
+    pkg,
+    wireMode === "canonical" ? void 0 : canonicalFormatLegacyResolver,
+    operation
+  );
+  const canonicalKind = typeof pkg.format_kind === "string" ? pkg.format_kind : void 0;
+  if (wireMode === "canonical") {
+    if (optionRefs.length > 0) {
+      next.format_option_refs = optionRefs.map((ref) => ({ ...ref }));
+    }
+    if (legacyRefs.length > 0) {
+      let mappedRefs = legacyRefs.flatMap((legacy) => {
+        const matches = candidates.filter((candidate) => sameLegacyIdentity(candidate.ref, legacy));
+        if (matches.length !== 1 || !matches[0].formatOptionRef) return [];
+        return [matches[0].formatOptionRef];
+      });
+      if (optionRefs.length === 0 && mappedRefs.length !== legacyRefs.length) {
+        const productId = typeof pkg.product_id === "string" ? pkg.product_id : "<package-selector>";
+        const projected = (0, import_v1_to_v2.projectV1ProductToV2)(
+          {
+            product_id: productId,
+            name: productId,
+            description: "legacy package selector normalization",
+            format_ids: legacyRefs
+          },
+          { legacyFormatConverter }
+        );
+        const projectedRefs = projected.v2.format_options.flatMap((option) => {
+          const ref = optionReference(option);
+          return ref ? [ref] : [];
+        });
+        if (projected.diagnostics.length > 0 || projectedRefs.length !== legacyRefs.length) {
+          throw new CreativeFormatProjectionError(
+            operation,
+            "(package selector)",
+            "legacy package format_ids cannot be converted to stable canonical format_option_refs"
+          );
+        }
+        mappedRefs = projectedRefs;
+      }
+      if (optionRefs.length === 0) next.format_option_refs = mappedRefs;
+    }
+    delete next.format_ids;
+  } else {
+    if (optionRefs.length > 0) {
+      const selectedCandidates = candidates.filter(
+        (candidate) => candidate.formatOptionRef && optionRefs.some((selected) => sameOptionReference(selected, candidate.formatOptionRef))
+      );
+      const everyOptionMapped = optionRefs.every(
+        (selected) => selectedCandidates.some(
+          (candidate) => candidate.formatOptionRef ? sameOptionReference(selected, candidate.formatOptionRef) : false
+        )
+      );
+      if (!everyOptionMapped || selectedCandidates.length === 0) {
+        let resolved;
+        try {
+          if (!containerOptsOutOfLegacy(pkg)) {
+            resolved = (0, import_v2_to_v1.resolveCanonicalFormatLegacyRefs)(canonicalFormatLegacyResolver, {
+              source: "selector",
+              selector: pkg,
+              operation,
+              field: "(package selector)"
+            });
+          }
+        } catch (error) {
+          if (!(error instanceof import_v2_to_v1.CanonicalFormatLegacyResolutionError)) throw error;
+          throw new CreativeFormatProjectionError(
+            operation,
+            "(package selector)",
+            "canonical format legacy resolver returned an invalid or ambiguous package mapping"
+          );
+        }
+        if (!resolved) {
+          throw new CreativeFormatProjectionError(
+            operation,
+            "(package selector)",
+            "canonical format_option_refs have no complete legacy representation; re-run getProducts() or configure canonicalFormatLegacyResolver for persisted selections"
+          );
+        }
+        next.format_ids = resolved;
+        delete next.format_option_refs;
+        delete next.format_kind;
+        return next;
+      }
+      next.format_ids = dedupeLegacyRefs(selectedCandidates.map((candidate) => candidate.ref));
+      delete next.format_option_refs;
+    } else if (canonicalKind) {
+      const selectedCandidates = candidates.filter((candidate) => candidate.formatKind === canonicalKind);
+      if (selectedCandidates.length === 1) {
+        next.format_ids = [{ ...selectedCandidates[0].ref }];
+      } else {
+        let resolved;
+        try {
+          if (!containerOptsOutOfLegacy(pkg, canonicalKind)) {
+            resolved = (0, import_v2_to_v1.resolveCanonicalFormatLegacyRefs)(
+              canonicalFormatLegacyResolver,
+              {
+                source: "selector",
+                selector: pkg,
+                operation,
+                field: "(package selector)"
+              },
+              true
+            );
+          }
+        } catch (error) {
+          if (!(error instanceof import_v2_to_v1.CanonicalFormatLegacyResolutionError)) throw error;
+          throw new CreativeFormatProjectionError(
+            operation,
+            "(package selector)",
+            "canonical format legacy resolver returned an invalid or ambiguous package mapping"
+          );
+        }
+        if (resolved) {
+          next.format_ids = resolved;
+        } else {
+          throw new CreativeFormatProjectionError(
+            operation,
+            "(package selector)",
+            "canonical package format_kind has no unambiguous legacy representation; select a format_option_ref from the product before delivery"
+          );
+        }
+      }
+    }
+    delete next.format_kind;
+  }
+  return next;
+}
+function canonicalizeCreative(creative, selectorContainer, operation, legacyFormatConverter) {
+  const creativeId = typeof creative.creative_id === "string" ? creative.creative_id : "(unknown)";
+  const hasCanonicalKind = typeof creative.format_kind === "string";
+  if (hasCanonicalKind && creative.format_id !== void 0) {
+    throw new CreativeFormatProjectionError(
+      operation,
+      creativeId,
+      "creative must not declare both canonical format_kind and legacy format_id"
+    );
+  }
+  if (hasCanonicalKind && creative.format_id === void 0) {
+    if (!CANONICAL_FORMAT_KINDS.has(creative.format_kind)) {
+      throw new CreativeFormatProjectionError(
+        operation,
+        creativeId,
+        `unknown canonical format_kind ${creative.format_kind}`
+      );
+    }
+    const creativeOptionRef = optionReference(creative.format_option_ref);
+    const selectedRefs = selectedOptionReferences(selectorContainer);
+    if (creativeOptionRef && selectedRefs.length > 0 && !selectedRefs.some((ref) => sameOptionReference(ref, creativeOptionRef))) {
+      throw new CreativeFormatProjectionError(
+        operation,
+        creativeId,
+        "creative format_option_ref conflicts with the package selected format_option_refs"
+      );
+    }
+    return creative;
+  }
+  const existing = legacyRef(creative.format_id);
+  if (!existing) {
+    throw new CreativeFormatProjectionError(
+      operation,
+      creativeId,
+      "creative must identify its format canonically with format_kind"
+    );
+  }
+  const matchingCandidates = candidatesFromContainer(selectorContainer).filter(
+    (candidate) => sameLegacyIdentity(candidate.ref, existing) && (existing.width === void 0 || candidate.ref.width === existing.width) && (existing.height === void 0 || candidate.ref.height === existing.height) && (existing.duration_ms === void 0 || candidate.ref.duration_ms === existing.duration_ms)
+  );
+  if (matchingCandidates.length === 1 && matchingCandidates[0].formatKind) {
+    const candidate = matchingCandidates[0];
+    const next2 = { ...creative, format_kind: candidate.formatKind };
+    delete next2.format_id;
+    if (candidate.formatOptionRef) next2.format_option_ref = candidate.formatOptionRef;
+    if (candidate.formatKind === "custom" && !candidate.formatOptionRef) {
+      throw new CreativeFormatProjectionError(
+        operation,
+        creativeId,
+        "custom product format must provide format_option_id so the canonical creative retains a concrete identity"
+      );
+    }
+    return next2;
+  }
+  const selectorCandidates = candidatesFromContainer(selectorContainer);
+  if (selectorCandidates.length > 0 && matchingCandidates.length !== 1) {
+    throw new CreativeFormatProjectionError(
+      operation,
+      creativeId,
+      matchingCandidates.length === 0 ? "legacy format reference conflicts with the selected seller format identity or constraints" : "legacy format reference is ambiguous within the selected seller format options"
+    );
+  }
+  const { v2, diagnostics } = (0, import_v1_to_v2.projectV1ProductToV2)(
+    {
+      product_id: `<creative:${creativeId}>`,
+      name: creativeId,
+      description: "legacy creative normalization",
+      format_ids: [existing]
+    },
+    { legacyFormatConverter }
+  );
+  const declaration = v2.format_options[0];
+  if (!declaration) {
+    const diagnostic = diagnostics[0];
+    const failure = diagnostic?.code === "FORMAT_PROJECTION_FAILED" ? diagnostic.error.details.resolution_failure : void 0;
+    throw new CreativeFormatProjectionError(
+      operation,
+      creativeId,
+      `legacy creative format has no canonical conversion${failure ? ` (${failure})` : ""}`
+    );
+  }
+  const next = { ...creative, format_kind: declaration.format_kind };
+  delete next.format_id;
+  const candidateOptionRef = matchingCandidates.length === 1 && matchingCandidates[0].formatKind === declaration.format_kind ? matchingCandidates[0].formatOptionRef : void 0;
+  const convertedOptionRef = optionReference(declaration) ?? candidateOptionRef;
+  if (convertedOptionRef) next.format_option_ref = convertedOptionRef;
+  if (declaration.format_kind === "custom" && !convertedOptionRef) {
+    throw new CreativeFormatProjectionError(
+      operation,
+      creativeId,
+      "custom legacy conversion must provide format_option_id so the canonical creative retains a concrete identity"
+    );
+  }
+  return next;
+}
+function projectCreativeForDelivery(creative, selectorContainer, wireMode = "canonical", operation = "creative_delivery", legacyFormatConverter, canonicalFormatLegacyResolver) {
+  const inputRecord = creative;
+  const originalLegacyRef = legacyRef(inputRecord.format_id);
+  const creativeRecord = canonicalizeCreative(inputRecord, selectorContainer, operation, legacyFormatConverter);
+  if (wireMode === "canonical") return creativeRecord;
+  if (originalLegacyRef) {
+    const selectedOriginal = selectLegacyRef(inputRecord, selectorContainer, canonicalFormatLegacyResolver, operation);
+    if (selectedOriginal) {
+      return projectCreative(creativeRecord, selectedOriginal);
+    }
+    throw new CreativeFormatProjectionError(
+      operation,
+      typeof inputRecord.creative_id === "string" ? inputRecord.creative_id : "(unknown)",
+      "the original legacy format reference conflicts with the selected seller format identity or constraints"
+    );
+  }
+  const formatId = selectLegacyRef(creativeRecord, selectorContainer, canonicalFormatLegacyResolver, operation);
+  if (formatId) return projectCreative(creativeRecord, formatId);
+  if (typeof creativeRecord.format_kind === "string") {
+    const creativeId = typeof creativeRecord.creative_id === "string" ? creativeRecord.creative_id : "(unknown)";
+    const allCandidates = candidatesFromContainer(selectorContainer, canonicalFormatLegacyResolver, operation);
+    let candidates = allCandidates.filter((candidate) => candidate.formatKind === creativeRecord.format_kind);
+    const constrained = candidates.filter((candidate) => refMatchesParams(candidate.ref, selectorContainer.params));
+    if (constrained.length > 0) candidates = constrained;
+    let resolved;
+    try {
+      if (!containerOptsOutOfLegacy(
+        selectorContainer,
+        creativeRecord.format_kind,
+        optionReference(creativeRecord.format_option_ref)
+      )) {
+        resolved = (0, import_v2_to_v1.resolveCanonicalFormatLegacyRefs)(
+          canonicalFormatLegacyResolver,
+          {
+            source: "creative",
+            creative: creativeRecord,
+            selector: selectorContainer,
+            operation,
+            field: creativeId
+          },
+          true
+        );
+      }
+    } catch (error) {
+      if (!(error instanceof import_v2_to_v1.CanonicalFormatLegacyResolutionError)) throw error;
+      throw new CreativeFormatProjectionError(
+        operation,
+        creativeId,
+        "canonical format legacy resolver returned an invalid or ambiguous creative mapping"
+      );
+    }
+    if (resolved) return projectCreative(creativeRecord, resolved[0]);
+    if (candidates.length > 1) {
+      throw new CreativeFormatProjectionError(
+        operation,
+        creativeId,
+        `the seller advertised ${candidates.length} legacy refs for canonical kind ${creativeRecord.format_kind}`
+      );
+    }
+    const reason = "the selected seller product did not provide one unambiguous legacy format reference";
+    throw new CreativeFormatProjectionError(operation, creativeId, reason);
+  }
+  return creative;
+}
+function projectMediaBuyCreativesForDelivery(request, wireMode = "canonical", operation = "create_media_buy", legacyFormatConverter, canonicalFormatLegacyResolver) {
+  const requestRecord = record(request);
+  if (!requestRecord) return request;
+  let changed = false;
+  const next = { ...requestRecord };
+  for (const key of ["packages", "new_packages"]) {
+    const packages = requestRecord[key];
+    if (!Array.isArray(packages)) continue;
+    next[key] = packages.map((packageValue) => {
+      const pkg = record(packageValue);
+      if (!pkg) return packageValue;
+      const creatives = Array.isArray(pkg.creatives) ? pkg.creatives.map((creativeValue) => {
+        const creative = record(creativeValue);
+        if (!creative) return creativeValue;
+        const projected = projectCreativeForDelivery(
+          creative,
+          pkg,
+          wireMode,
+          operation,
+          legacyFormatConverter,
+          canonicalFormatLegacyResolver
+        );
+        if (projected !== creativeValue) changed = true;
+        return projected;
+      }) : void 0;
+      const projectedPackage = projectPackageSelectors(
+        pkg,
+        wireMode,
+        operation,
+        legacyFormatConverter,
+        canonicalFormatLegacyResolver
+      );
+      if (projectedPackage !== packageValue) changed = true;
+      return creatives ? { ...projectedPackage, creatives } : projectedPackage;
+    });
+  }
+  return changed ? next : request;
+}
+function projectSyncCreativesForDelivery(request, selectorContainers, wireMode = "canonical", legacyFormatConverter, canonicalFormatLegacyResolver) {
+  const requestRecord = record(request);
+  if (!requestRecord || !Array.isArray(requestRecord.creatives)) {
+    return request;
+  }
+  const assignments = Array.isArray(requestRecord.assignments) ? requestRecord.assignments : [];
+  let changed = false;
+  const creatives = requestRecord.creatives.map((creativeValue) => {
+    const creative = record(creativeValue);
+    if (!creative) return creativeValue;
+    const assignedPackageIds = new Set(
+      assignments.flatMap((assignmentValue) => {
+        const assignment = record(assignmentValue);
+        if (!assignment || assignment.creative_id !== creative.creative_id) return [];
+        return typeof assignment.package_id === "string" ? [assignment.package_id] : [];
+      })
+    );
+    const relevant = assignedPackageIds.size === 0 ? selectorContainers : selectorContainers.filter(
+      (container) => typeof container.package_id === "string" && assignedPackageIds.has(container.package_id)
+    );
+    const combined = {
+      selector_containers: relevant
+    };
+    const projected = projectCreativeForDelivery(
+      creative,
+      combined,
+      wireMode,
+      "sync_creatives",
+      legacyFormatConverter,
+      canonicalFormatLegacyResolver
+    );
+    if (projected !== creativeValue) changed = true;
+    return projected;
+  });
+  return changed ? { ...requestRecord, creatives } : request;
+}
+function release(value) {
+  if (typeof value !== "string") return void 0;
+  const match = /^v?(\d+)\.(\d+)(?:\.|-|$)/.exec(value.trim());
+  return match ? { major: Number(match[1]), minor: Number(match[2]), label: value } : void 0;
+}
+function mutuallyServedRelease(caps, raw, requestedVersion) {
+  const requested = release(requestedVersion);
+  if (!requested) return void 0;
+  const normalizedSupported = Array.isArray(caps?.supportedVersions) ? caps.supportedVersions : [];
+  const directSupported = record(caps?.adcp)?.supported_versions;
+  const rawSupported = record(raw?.adcp)?.supported_versions;
+  const advertisedValues = [
+    ...normalizedSupported,
+    ...Array.isArray(directSupported) ? directSupported : [],
+    ...Array.isArray(rawSupported) ? rawSupported : []
+  ];
+  const advertised = advertisedValues.flatMap((value) => {
+    const parsed = release(value);
+    return parsed ? [parsed] : [];
+  });
+  if (advertisedValues.length > 0 && advertised.length === 0) {
+    throw new CreativeFormatCapabilityError(
+      "Seller advertised supported AdCP versions, but none were valid release identifiers"
+    );
+  }
+  if (advertised.length === 0) {
+    return requested.major < 3 || requested.major === 3 && requested.minor === 0 ? requested : void 0;
+  }
+  const mutuallyServed = advertised.filter(
+    (candidate) => candidate.major === requested.major && (candidate.minor < requested.minor || candidate.minor === requested.minor)
+  ).sort((left, right) => right.minor - left.minor)[0];
+  if (!mutuallyServed) {
+    const supported = [...new Set(advertised.map((candidate) => candidate.label))].join(", ");
+    throw new CreativeFormatCapabilityError(
+      `No mutually supported AdCP release: client requested ${requestedVersion}, seller advertised ${supported}`
+    );
+  }
+  return mutuallyServed;
+}
+function resolveCreativeFormatWireMode(capabilities, negotiatedVersion) {
+  const caps = record(capabilities);
+  const raw = record(caps?._raw);
+  const features = record(caps?.features);
+  const mediaBuyFeatures = record(record(caps?.media_buy)?.features);
+  const rawMediaBuyFeatures = record(record(raw?.media_buy)?.features);
+  const declarations = [
+    features?.canonicalCreatives,
+    mediaBuyFeatures?.canonical_creatives,
+    rawMediaBuyFeatures?.canonical_creatives
+  ].filter((value) => typeof value === "boolean");
+  if (declarations.includes(true) && declarations.includes(false)) {
+    throw new CreativeFormatCapabilityError(
+      "Seller capability response contains conflicting canonical_creatives declarations"
+    );
+  }
+  const explicitCanonical = declarations[0];
+  const negotiated = mutuallyServedRelease(caps, raw, negotiatedVersion);
+  if (caps?.version === "v2") return "legacy";
+  if (negotiated && (negotiated.major > 3 || negotiated.major === 3 && negotiated.minor >= 2)) {
+    if (explicitCanonical === false) {
+      throw new CreativeFormatCapabilityError(
+        `AdCP ${negotiated.label} guarantees canonical creatives, but the seller advertised canonical_creatives: false`
+      );
+    }
+    return "canonical";
+  }
+  if (negotiated && (negotiated.major < 3 || negotiated.major === 3 && negotiated.minor === 0)) {
+    return "legacy";
+  }
+  if (!caps) return "unknown";
+  if (explicitCanonical === true) return "canonical";
+  if (explicitCanonical === false) return "legacy";
+  return "unknown";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CreativeFormatCapabilityError,
+  CreativeFormatProjectionError,
+  projectCreativeForDelivery,
+  projectMediaBuyCreativesForDelivery,
+  projectSyncCreativesForDelivery,
+  resolveCreativeFormatWireMode,
+  stripLegacyCreativeIdentity
+});
+//# sourceMappingURL=creative-delivery.js.map