@adcp/sdk 16.1.0 → 16.3.0

package/dist/lib/testing/storyboard/collection-selection.js

@@ -0,0 +1,384 @@
+"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 collection_selection_exports = {};
+__export(collection_selection_exports, {
+  COLLECTION_DIAGNOSTIC_LIMIT: () => COLLECTION_DIAGNOSTIC_LIMIT,
+  COLLECTION_PAIR_LIMIT: () => COLLECTION_PAIR_LIMIT,
+  COLLECTION_TARGETING_MODES: () => COLLECTION_TARGETING_MODES,
+  COLLECTION_WITNESS_KINDS: () => COLLECTION_WITNESS_KINDS,
+  compareCollectionPairs: () => compareCollectionPairs,
+  diffCollectionPairSets: () => diffCollectionPairSets,
+  evaluateCollectionSelection: () => evaluateCollectionSelection,
+  formatCollectionPair: () => formatCollectionPair,
+  normalizeCollectionSelectionSelector: () => normalizeCollectionSelectionSelector,
+  normalizeCollectionSelectors: () => normalizeCollectionSelectors,
+  productSatisfiesCollectionSelection: () => productSatisfiesCollectionSelection,
+  readCollectionWitness: () => readCollectionWitness,
+  summarizeCollectionPairs: () => summarizeCollectionPairs
+});
+module.exports = __toCommonJS(collection_selection_exports);
+const PAIR_LIMIT_DEFAULT = 1e4;
+const COLLECTION_PAIR_LIMIT = PAIR_LIMIT_DEFAULT;
+const COLLECTION_DIAGNOSTIC_LIMIT = 20;
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function utf8Compare(a, b) {
+  return Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
+}
+function compareCollectionPairs(a, b) {
+  const domain = utf8Compare(a.publisher_domain, b.publisher_domain);
+  if (domain !== 0) return domain;
+  if (a.collection_id === b.collection_id) return 0;
+  if (a.collection_id === null) return -1;
+  if (b.collection_id === null) return 1;
+  return utf8Compare(a.collection_id, b.collection_id);
+}
+function formatCollectionPair(pair) {
+  return pair.collection_id === null ? `${JSON.stringify(pair.publisher_domain)}:*` : `${JSON.stringify(pair.publisher_domain)}:${JSON.stringify(pair.collection_id)}`;
+}
+function pairKey(pair) {
+  return pair.collection_id === null ? `${JSON.stringify(pair.publisher_domain)}\0` : `${JSON.stringify(pair.publisher_domain)}\0${JSON.stringify(pair.collection_id)}`;
+}
+function normalizeCollectionSelectors(value, options = {}) {
+  const limit = options.limit ?? PAIR_LIMIT_DEFAULT;
+  if (!Array.isArray(value)) {
+    return {
+      ok: false,
+      failure: {
+        code: "not_an_array",
+        detail: `expected an array of collection selectors; received ${describe(value)}`
+      }
+    };
+  }
+  const seen = /* @__PURE__ */ new Map();
+  for (let index = 0; index < value.length; index++) {
+    const selector = value[index];
+    if (!isRecord(selector)) {
+      return {
+        ok: false,
+        failure: {
+          code: "selector_not_object",
+          detail: `collections[${index}] must be an object; received ${describe(selector)}`
+        }
+      };
+    }
+    const domain = selector.publisher_domain;
+    if (typeof domain !== "string" || domain.length === 0) {
+      return {
+        ok: false,
+        failure: {
+          code: "publisher_domain_invalid",
+          detail: `collections[${index}].publisher_domain must be a non-empty string; received ${describe(domain)}`
+        }
+      };
+    }
+    const ids = selector.collection_ids;
+    if (ids === void 0 || ids === null) {
+      addPair(seen, { publisher_domain: domain, collection_id: null });
+    } else {
+      if (!Array.isArray(ids) || ids.length === 0) {
+        return {
+          ok: false,
+          failure: {
+            code: "collection_ids_invalid",
+            detail: `collections[${index}].collection_ids must be a non-empty array when present; received ${describe(ids)}`
+          }
+        };
+      }
+      for (let idIndex = 0; idIndex < ids.length; idIndex++) {
+        const id = ids[idIndex];
+        if (typeof id !== "string") {
+          return {
+            ok: false,
+            failure: {
+              code: "collection_id_invalid",
+              detail: `collections[${index}].collection_ids[${idIndex}] must be a string; received ${describe(id)}`
+            }
+          };
+        }
+        addPair(seen, { publisher_domain: domain, collection_id: id });
+        if (seen.size > limit) return pairLimitExceeded(limit, index);
+      }
+    }
+    if (seen.size > limit) return pairLimitExceeded(limit, index);
+  }
+  const pairs = [...seen.values()].sort(compareCollectionPairs);
+  const domains = [...new Set(pairs.map((pair) => pair.publisher_domain))].sort(utf8Compare);
+  return { ok: true, value: { pairs, selector_count: value.length, domains } };
+}
+function pairLimitExceeded(limit, index) {
+  return {
+    ok: false,
+    failure: {
+      code: "pair_limit_exceeded",
+      detail: `normalized collection pairs exceeded the ${limit}-pair safety limit at collections[${index}]`
+    }
+  };
+}
+function addPair(seen, pair) {
+  const key = pairKey(pair);
+  if (!seen.has(key)) seen.set(key, pair);
+}
+function describe(value) {
+  if (value === void 0) return "undefined";
+  if (value === null) return "null";
+  if (Array.isArray(value)) return `an array of length ${value.length}`;
+  return typeof value === "object" ? "an object" : JSON.stringify(value);
+}
+function diffCollectionPairSets(actual, expected) {
+  const expectedKeys = new Set(expected.map(pairKey));
+  const actualKeys = new Set(actual.map(pairKey));
+  const missing = expected.filter((pair) => !actualKeys.has(pairKey(pair)));
+  const unexpected = actual.filter((pair) => !expectedKeys.has(pairKey(pair)));
+  return { equal: missing.length === 0 && unexpected.length === 0, missing, unexpected };
+}
+function summarizeCollectionPairs(pairs) {
+  const shown = pairs.slice(0, COLLECTION_DIAGNOSTIC_LIMIT).map(formatCollectionPair);
+  const elided = pairs.length - shown.length;
+  return elided > 0 ? `${shown.join(", ")} (+${elided} more)` : shown.join(", ");
+}
+const COLLECTION_TARGETING_MODES = ["selectable", "fixed", "any"];
+function normalizeCollectionSelectionSelector(value, location) {
+  if (!isRecord(value)) throw new Error(`${location}: must be an object`);
+  const unknown = Object.keys(value).filter(
+    (key) => !["collection_targeting", "minimum_pairs", "require_cross_publisher_collection"].includes(key)
+  );
+  if (unknown.length > 0) {
+    throw new Error(`${location}: unknown key(s): ${unknown.join(", ")}; the operand is closed`);
+  }
+  const targeting = value.collection_targeting;
+  if (typeof targeting !== "string" || !COLLECTION_TARGETING_MODES.includes(targeting)) {
+    throw new Error(`${location}.collection_targeting: must be one of ${COLLECTION_TARGETING_MODES.join(", ")}`);
+  }
+  let minimumPairs = 1;
+  if (value.minimum_pairs !== void 0) {
+    if (value.minimum_pairs !== 1 && value.minimum_pairs !== 2) {
+      throw new Error(`${location}.minimum_pairs: must be 1 or 2`);
+    }
+    minimumPairs = value.minimum_pairs;
+  }
+  if (value.require_cross_publisher_collection !== void 0 && typeof value.require_cross_publisher_collection !== "boolean") {
+    throw new Error(`${location}.require_cross_publisher_collection: must be boolean`);
+  }
+  return {
+    collection_targeting: targeting,
+    minimum_pairs: minimumPairs,
+    require_cross_publisher_collection: value.require_cross_publisher_collection === true
+  };
+}
+function collectHostDomains(candidate) {
+  const domains = /* @__PURE__ */ new Set();
+  const properties = candidate.publisher_properties;
+  if (Array.isArray(properties)) {
+    for (const entry of properties) {
+      if (!isRecord(entry)) continue;
+      if (typeof entry.publisher_domain === "string" && entry.publisher_domain.length > 0) {
+        domains.add(entry.publisher_domain);
+      }
+    }
+  }
+  return [...domains].sort(utf8Compare);
+}
+function cloneSelectorBundle(value) {
+  return value.map((selector) => ({
+    publisher_domain: selector.publisher_domain,
+    ...Array.isArray(selector.collection_ids) && { collection_ids: [...selector.collection_ids] }
+  }));
+}
+function buildUndeclaredCollectionIdSelectors(domain, pairs) {
+  const taken = new Set(pairs.filter((pair) => pair.publisher_domain === domain).map((pair) => pair.collection_id));
+  let candidate = "adcp-absent-collection";
+  for (let suffix = 0; taken.has(candidate); suffix++) {
+    candidate = `adcp-absent-collection-${suffix}`;
+  }
+  return [{ publisher_domain: domain, collection_ids: [candidate] }];
+}
+function buildUndeclaredPublisherDomainSelectors(domains, collectionId) {
+  let candidate = "adcp-absent-owner.invalid";
+  for (let suffix = 0; domains.has(candidate); suffix++) {
+    candidate = `adcp-absent-owner-${suffix}.invalid`;
+  }
+  return [{ publisher_domain: candidate, collection_ids: [collectionId] }];
+}
+function evaluateCollectionSelection(candidate, selector) {
+  if (selector !== null && typeof selector === "object" && "declared_selectors" in selector) {
+    throw new Error(
+      'evaluateCollectionSelection: received a CollectionSelectionWitness where a CollectionSelectionSelector was expected. A witness is the OUTPUT of an evaluation, not an operand; build the operand explicitly, e.g. { collection_targeting: "selectable", minimum_pairs: 2 }.'
+    );
+  }
+  const resolved = {
+    collection_targeting: selector.collection_targeting,
+    minimum_pairs: selector.minimum_pairs ?? 1,
+    require_cross_publisher_collection: selector.require_cross_publisher_collection === true
+  };
+  return evaluateResolvedCollectionSelection(candidate, resolved);
+}
+function evaluateResolvedCollectionSelection(candidate, selector) {
+  if (!isRecord(candidate)) return { eligible: false, reason: "candidate is not an object" };
+  const flag = candidate.collection_targeting_allowed;
+  if (flag !== void 0 && typeof flag !== "boolean") {
+    return {
+      eligible: false,
+      reason: `collection_targeting_allowed must be boolean or absent; observed ${describe(flag)}`
+    };
+  }
+  const effectiveTargeting = flag === true ? "selectable" : "fixed";
+  if (selector.collection_targeting !== "any" && selector.collection_targeting !== effectiveTargeting) {
+    return {
+      eligible: false,
+      reason: selector.collection_targeting === "fixed" ? "collection_targeting_allowed is true; a fixed bundle requires literal false or absence" : "collection_targeting_allowed is not literal true"
+    };
+  }
+  const normalized = normalizeCollectionSelectors(candidate.collections);
+  if (!normalized.ok) {
+    return { eligible: false, reason: `collections did not normalize: ${normalized.failure.detail}` };
+  }
+  if (normalized.value.pairs.some((pair) => pair.collection_id === null)) {
+    return {
+      eligible: false,
+      reason: "product collections contain a domain-only bulk-grant selector; product composition requires explicit collection_ids on every entry"
+    };
+  }
+  const concrete = normalized.value.pairs;
+  if (concrete.length < selector.minimum_pairs) {
+    return {
+      eligible: false,
+      reason: `product exposes ${concrete.length} distinct concrete collection pair(s); ${selector.minimum_pairs} required`
+    };
+  }
+  const hostDomains = collectHostDomains(candidate);
+  const bundle = cloneSelectorBundle(candidate.collections);
+  let relation = null;
+  if (selector.require_cross_publisher_collection) {
+    const hostSet = new Set(hostDomains);
+    const externalDomain = normalized.value.domains.find((domain) => !hostSet.has(domain));
+    if (externalDomain === void 0) {
+      return {
+        eligible: false,
+        reason: hostDomains.length === 0 ? "product declares no publisher_properties domains, so no owner/host relation is observable" : "every collection namespace is also a declared property namespace"
+      };
+    }
+    const carrying = bundle.filter((entry) => entry.publisher_domain === externalDomain).sort((left, right) => {
+      const l = JSON.stringify([...left.collection_ids ?? []].sort());
+      const r = JSON.stringify([...right.collection_ids ?? []].sort());
+      return l < r ? -1 : l > r ? 1 : 0;
+    })[0];
+    relation = {
+      collection_publisher_domain: externalDomain,
+      property_publisher_domains: hostDomains,
+      selector: {
+        ...carrying,
+        ...carrying.collection_ids && { collection_ids: [...carrying.collection_ids] }
+      }
+    };
+  }
+  const subsetSource = relation === null ? concrete[0] : (
+    // Non-null is sound, not optimism: `relation.collection_publisher_domain`
+    // is taken from `normalized.value.domains`, which is derived from
+    // `concrete`, so the domain is present by construction. The previous
+    // `?? concrete[0]` read as a carriage-vs-local fallback and was not
+    // one — it could only ever have masked a normalizer bug.
+    concrete.find((pair) => pair.publisher_domain === relation.collection_publisher_domain)
+  );
+  const strictSubset = concrete.length >= 2 ? [{ publisher_domain: subsetSource.publisher_domain, collection_ids: [subsetSource.collection_id] }] : null;
+  const witness = {
+    product_id: typeof candidate.product_id === "string" ? candidate.product_id : null,
+    collection_targeting: effectiveTargeting,
+    collection_targeting_allowed: flag,
+    declared_selectors: bundle,
+    distinct_pairs: concrete,
+    strict_subset: strictSubset,
+    undeclared_collection_id_selectors: buildUndeclaredCollectionIdSelectors(
+      subsetSource.publisher_domain,
+      normalized.value.pairs
+    ),
+    undeclared_publisher_domain_selectors: buildUndeclaredPublisherDomainSelectors(
+      new Set(normalized.value.domains),
+      subsetSource.collection_id
+    ),
+    cross_publisher_relation: relation,
+    property_publisher_domains: hostDomains
+  };
+  return { eligible: true, witness };
+}
+function productSatisfiesCollectionSelection(candidate, selector) {
+  return evaluateCollectionSelection(candidate, selector).eligible;
+}
+const COLLECTION_WITNESS_KINDS = [
+  "declared_selectors",
+  "distinct_pairs",
+  "strict_subset",
+  "undeclared_collection_id_selectors",
+  "undeclared_publisher_domain_selectors",
+  "cross_publisher_relation",
+  "property_publisher_domains"
+];
+function readCollectionWitness(witness, kind) {
+  if (!witness) {
+    return {
+      ok: false,
+      detail: `witness capture "${kind}" requires a collection_selection_satisfies predicate on the same declaration`
+    };
+  }
+  switch (kind) {
+    case "declared_selectors":
+      return { ok: true, value: witness.declared_selectors };
+    case "distinct_pairs":
+      return { ok: true, value: witness.distinct_pairs };
+    case "strict_subset":
+      if (witness.strict_subset === null) {
+        return {
+          ok: false,
+          detail: "strict_subset requires a product with at least two distinct concrete collection pairs; declare minimum_pairs: 2"
+        };
+      }
+      return { ok: true, value: witness.strict_subset };
+    case "undeclared_collection_id_selectors":
+      return { ok: true, value: witness.undeclared_collection_id_selectors };
+    case "undeclared_publisher_domain_selectors":
+      return { ok: true, value: witness.undeclared_publisher_domain_selectors };
+    case "cross_publisher_relation":
+      if (witness.cross_publisher_relation === null) {
+        return {
+          ok: false,
+          detail: "cross_publisher_relation requires require_cross_publisher_collection: true on the collection_selection_satisfies operand"
+        };
+      }
+      return { ok: true, value: witness.cross_publisher_relation };
+    case "property_publisher_domains":
+      return { ok: true, value: witness.property_publisher_domains };
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  COLLECTION_DIAGNOSTIC_LIMIT,
+  COLLECTION_PAIR_LIMIT,
+  COLLECTION_TARGETING_MODES,
+  COLLECTION_WITNESS_KINDS,
+  compareCollectionPairs,
+  diffCollectionPairSets,
+  evaluateCollectionSelection,
+  formatCollectionPair,
+  normalizeCollectionSelectionSelector,
+  normalizeCollectionSelectors,
+  productSatisfiesCollectionSelection,
+  readCollectionWitness,
+  summarizeCollectionPairs
+});