@adcp/sdk 17.0.0-beta.13 → 17.0.0-beta.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/dist/lib/brand/index.d.mts +2 -0
  2. package/dist/lib/brand/index.d.ts +2 -0
  3. package/dist/lib/brand/index.js +3 -0
  4. package/dist/lib/brand/index.mjs +2 -0
  5. package/dist/lib/brand/selection.d.mts +13 -0
  6. package/dist/lib/brand/selection.d.ts +13 -0
  7. package/dist/lib/brand/selection.js +83 -0
  8. package/dist/lib/brand/selection.mjs +59 -0
  9. package/dist/lib/index.d.mts +2 -2
  10. package/dist/lib/index.d.ts +2 -2
  11. package/dist/lib/index.js +2 -0
  12. package/dist/lib/index.mjs +2 -0
  13. package/dist/lib/registry/types.d.mts +5 -0
  14. package/dist/lib/registry/types.d.ts +5 -0
  15. package/dist/lib/registry/types.generated.d.ts +4 -0
  16. package/dist/lib/server/decisioning/runtime/from-platform.js +12 -2
  17. package/dist/lib/server/decisioning/runtime/from-platform.mjs +12 -2
  18. package/dist/lib/server/test-controller.d.mts +9 -35
  19. package/dist/lib/server/test-controller.d.ts +9 -35
  20. package/dist/lib/server/test-controller.js +4 -0
  21. package/dist/lib/server/test-controller.mjs +4 -0
  22. package/dist/lib/testing/comply-controller.d.mts +7 -10
  23. package/dist/lib/testing/comply-controller.d.ts +7 -10
  24. package/dist/lib/testing/reporting/doctor.js +2 -1
  25. package/dist/lib/testing/reporting/doctor.mjs +2 -1
  26. package/dist/lib/testing/storyboard/account-policy.d.mts +42 -0
  27. package/dist/lib/testing/storyboard/account-policy.d.ts +42 -0
  28. package/dist/lib/testing/storyboard/account-policy.js +41 -2
  29. package/dist/lib/testing/storyboard/account-policy.mjs +38 -1
  30. package/dist/lib/testing/storyboard/path.d.mts +6 -0
  31. package/dist/lib/testing/storyboard/path.d.ts +6 -0
  32. package/dist/lib/testing/storyboard/path.js +22 -0
  33. package/dist/lib/testing/storyboard/path.mjs +21 -0
  34. package/dist/lib/testing/storyboard/request-builder.js +1 -1
  35. package/dist/lib/testing/storyboard/request-builder.mjs +1 -1
  36. package/dist/lib/testing/storyboard/runner.d.mts +1 -42
  37. package/dist/lib/testing/storyboard/runner.d.ts +1 -42
  38. package/dist/lib/testing/storyboard/runner.js +8 -38
  39. package/dist/lib/testing/storyboard/runner.mjs +5 -35
  40. package/dist/lib/testing/storyboard/seeding.js +152 -2
  41. package/dist/lib/testing/storyboard/seeding.mjs +152 -2
  42. package/dist/lib/testing/storyboard/types.d.mts +4 -2
  43. package/dist/lib/testing/storyboard/types.d.ts +4 -2
  44. package/dist/lib/testing/storyboard/types.js +1 -0
  45. package/dist/lib/testing/storyboard/types.mjs +1 -0
  46. package/dist/lib/testing/storyboard/validations.d.mts +1 -1
  47. package/dist/lib/testing/storyboard/validations.d.ts +1 -1
  48. package/dist/lib/testing/storyboard/validations.js +60 -1
  49. package/dist/lib/testing/storyboard/validations.mjs +61 -1
  50. package/dist/lib/v2/projection/creative-delivery.js +62 -16
  51. package/dist/lib/v2/projection/creative-delivery.mjs +62 -16
  52. package/dist/lib/version.d.mts +3 -3
  53. package/dist/lib/version.d.ts +3 -3
  54. package/dist/lib/version.js +3 -3
  55. package/dist/lib/version.mjs +3 -3
  56. package/docs/TYPE-SUMMARY.md +1 -1
  57. package/docs/guides/BRAND-ENTRY-SELECTION.md +56 -0
  58. package/docs/guides/REPORTING-LEDGER.md +142 -12
  59. package/docs/guides/REPORTING-OPERATIONS.md +18 -5
  60. package/docs/guides/VALIDATE-YOUR-AGENT.md +44 -0
  61. package/docs/llms.txt +1 -1
  62. package/docs/migration-14.x-rc-worksheet.md +4 -4
  63. package/docs/migration-reporting-row-storage-alignment.md +4 -2
  64. package/package.json +1 -1
@@ -18,6 +18,7 @@ import {
18
18
  parsePathWithWildcards,
19
19
  resolvePath,
20
20
  resolvePathAll,
21
+ iteratePathAll,
21
22
  resolvePortableIdentifierPathAll,
22
23
  toJsonPointer,
23
24
  validatePortableIdentifierPath,
@@ -89,6 +90,7 @@ function runValidation(validation, ctx) {
89
90
  return validateFieldValueOrAbsent(validation, resolveTarget(ctx));
90
91
  case "field_pattern":
91
92
  return validateFieldPattern(validation, resolveTarget(ctx));
93
+ case "field_excludes":
92
94
  case "field_contains":
93
95
  return validateFieldContains(validation, resolveTarget(ctx));
94
96
  case "status_code":
@@ -952,7 +954,7 @@ function validateFieldPattern(validation, taskResult) {
952
954
  }
953
955
  function validateFieldContains(validation, taskResult) {
954
956
  const checkName = validation.check;
955
- if (!validation.path) {
957
+ if (typeof validation.path !== "string" || !validation.path) {
956
958
  return {
957
959
  check: checkName,
958
960
  passed: false,
@@ -964,6 +966,18 @@ function validateFieldContains(validation, taskResult) {
964
966
  actual: null
965
967
  };
966
968
  }
969
+ if (validation.allowed_values !== void 0 && !Array.isArray(validation.allowed_values)) {
970
+ return {
971
+ check: checkName,
972
+ passed: false,
973
+ description: validation.description,
974
+ path: validation.path,
975
+ json_pointer: toJsonPointer(validation.path),
976
+ error: `${checkName} allowed_values must be an array`,
977
+ expected: "an array of values",
978
+ actual: validation.allowed_values
979
+ };
980
+ }
967
981
  if (validation.value === void 0 && !validation.allowed_values?.length) {
968
982
  return {
969
983
  check: checkName,
@@ -976,6 +990,9 @@ function validateFieldContains(validation, taskResult) {
976
990
  actual: null
977
991
  };
978
992
  }
993
+ if (checkName === "field_excludes") {
994
+ return validateFieldExcludes(validation, taskResult);
995
+ }
979
996
  const resolved = resolvePathAll(taskResult.data, validation.path);
980
997
  const pointer = toJsonPointer(validation.path);
981
998
  const candidates = validation.allowed_values?.length ? validation.allowed_values : [validation.value];
@@ -1003,6 +1020,49 @@ function validateFieldContains(validation, taskResult) {
1003
1020
  actual: resolved
1004
1021
  };
1005
1022
  }
1023
+ function validateFieldExcludes(validation, taskResult) {
1024
+ const path = validation.path;
1025
+ const candidates = validation.allowed_values?.length ? validation.allowed_values : [validation.value];
1026
+ const expected = { excludes: validation.allowed_values?.length ? validation.allowed_values : validation.value };
1027
+ const base = {
1028
+ check: validation.check,
1029
+ description: validation.description,
1030
+ path,
1031
+ json_pointer: toJsonPointer(path)
1032
+ };
1033
+ const unresolvedContext = (value) => {
1034
+ if (typeof value === "string") return /^\$context\./.test(value);
1035
+ if (Array.isArray(value)) return value.some(unresolvedContext);
1036
+ return value !== null && typeof value === "object" && Object.values(value).some(unresolvedContext);
1037
+ };
1038
+ if (candidates.some(unresolvedContext)) {
1039
+ return {
1040
+ ...base,
1041
+ passed: false,
1042
+ error: "field_excludes comparator contains an unresolved context reference",
1043
+ expected: "a resolved value or allowed_values comparator",
1044
+ actual: candidates
1045
+ };
1046
+ }
1047
+ if (path.length > 1024 || !/^[^.[\]]+(?:\[(?:\d+|\*)?\]|\.[^.[\]]+)*$/.test(path) || parsePathWithWildcards(path).some(
1048
+ (segment) => typeof segment === "string" && ["__proto__", "constructor", "prototype"].includes(segment)
1049
+ )) {
1050
+ return {
1051
+ ...base,
1052
+ passed: false,
1053
+ error: "Invalid field_excludes path",
1054
+ expected: "a valid safe storyboard path",
1055
+ actual: path
1056
+ };
1057
+ }
1058
+ const comparisonKey = comparisonKeyFromPath(path);
1059
+ for (const actual of iteratePathAll(taskResult.data, path)) {
1060
+ if (candidates.some((candidate) => containsValueMatches(actual, candidate, comparisonKey))) {
1061
+ return { ...base, passed: false, error: `Prohibited value found at ${path}`, expected, actual: [actual] };
1062
+ }
1063
+ }
1064
+ return { ...base, passed: true };
1065
+ }
1006
1066
  function validateArrayLength(validation, taskResult) {
1007
1067
  const checkName = "array_length";
1008
1068
  if (!validation.path) {
@@ -72,9 +72,10 @@ function stripLegacyCreativeIdentity(value) {
72
72
  const nonCreativeAgentContext = (key) => typeof key === "string" && !/(^|_)(?:creative|format|legacy)($|_)/.test(key) && /(^|_)(?:agents?|agent_details|agent_info)($|_)/.test(key);
73
73
  const nonCreativeSignalContext = (owner, key) => ownDataValue(owner, "source") === "agent" && typeof key === "string" && /(^|_)signal_ids?($|_)/.test(key);
74
74
  const nonCreativeListContext = (owner, key) => typeof ownDataValue(owner, "list_id") === "string" && typeof key === "string" && /(^|_)(?:property_list|collection_list|list_ref)($|_)/.test(key);
75
- const explicitNonCreativeContextKey = (key) => nonCreativeAgentContext(key) || typeof key === "string" && /(^|_)(?:signal_ids?|property_list|collection_list|list_ref)($|_)/.test(key);
75
+ const nonCreativeVerifierContext = (key) => key === "accepted_verifiers";
76
+ const explicitNonCreativeContextKey = (key) => nonCreativeAgentContext(key) || nonCreativeVerifierContext(key) || typeof key === "string" && /(^|_)(?:signal_ids?|property_list|collection_list|list_ref)($|_)/.test(key);
76
77
  const standaloneLegacyTuple = (owner, ownerKey) => {
77
- if (nonCreativeAgentContext(ownerKey) || nonCreativeSignalContext(owner, ownerKey) || nonCreativeListContext(owner, ownerKey)) {
78
+ if (nonCreativeAgentContext(ownerKey) || nonCreativeVerifierContext(ownerKey) || nonCreativeSignalContext(owner, ownerKey) || nonCreativeListContext(owner, ownerKey)) {
78
79
  return false;
79
80
  }
80
81
  if (typeof ownDataValue(owner, "agent_url") !== "string" || typeof ownDataValue(owner, "id") !== "string") {
@@ -85,7 +86,7 @@ function stripLegacyCreativeIdentity(value) {
85
86
  const preservesNonCreativeAgentUrl = (key, owner, ownerKey) => {
86
87
  if (!/(^|_)agent_url($|_)/.test(key)) return false;
87
88
  if (key === "agent_url") {
88
- return nonCreativeAgentContext(ownerKey) || nonCreativeSignalContext(owner, ownerKey) || nonCreativeListContext(owner, ownerKey) || typeof ownDataValue(owner, "id") === "string" && !standaloneLegacyTuple(owner, ownerKey);
89
+ return nonCreativeAgentContext(ownerKey) || nonCreativeVerifierContext(ownerKey) || nonCreativeSignalContext(owner, ownerKey) || nonCreativeListContext(owner, ownerKey) || typeof ownDataValue(owner, "id") === "string" && !standaloneLegacyTuple(owner, ownerKey);
89
90
  }
90
91
  return !/(^|_)(?:creative|format|legacy|offending|target|input|output)($|_)/.test(key);
91
92
  };
@@ -664,8 +665,7 @@ function preferMostConstrainedLegacyCandidates(candidates, creative) {
664
665
  const specific = remaining.filter((candidate) => legacyIdPinsDimensions(candidate.ref) === true);
665
666
  return specific.length > 0 && specific.length < remaining.length ? specific : remaining;
666
667
  }
667
- function selectLegacyRef(creative, container, canonicalFormatLegacyResolver, operation = "creative_delivery") {
668
- let candidates = candidatesFromContainer(container, canonicalFormatLegacyResolver, operation);
668
+ function selectLegacyRef(creative, container, canonicalFormatLegacyResolver, operation = "creative_delivery", candidates = candidatesFromContainer(container, canonicalFormatLegacyResolver, operation)) {
669
669
  const creativeOptionRef = optionReference(creative.format_option_ref);
670
670
  const selectedOptionRefs = Array.isArray(container.format_option_refs) ? container.format_option_refs.flatMap((value) => {
671
671
  const ref = optionReference(value);
@@ -1589,9 +1589,12 @@ function reconcileLegacyAssignmentRefs(resolved) {
1589
1589
  (0, import_legacy_metadata.transferLegacyCreativeMetadata)(source.value, value);
1590
1590
  return { value };
1591
1591
  }
1592
- function projectAssignedCreative(creative, packageIds, selectors, converter, resolver, definitions, options) {
1592
+ function projectAssignedCreative(creative, packageIds, selectors, converter, resolver, definitions, options, search) {
1593
+ const sharedIdentity = search?.identity;
1594
+ const packageResolvers = search?.resolvers ?? /* @__PURE__ */ new Map();
1593
1595
  const packageRefs = [];
1594
1596
  const resolved = [];
1597
+ let sharedCandidates;
1595
1598
  const parameterKeys = /* @__PURE__ */ new Set();
1596
1599
  let compatibleParameters = true;
1597
1600
  const playerSized = creative.format_kind === "video_vast" || creative.format_kind === "audio_vast";
@@ -1619,7 +1622,8 @@ function projectAssignedCreative(creative, packageIds, selectors, converter, res
1619
1622
  for (const packageId of packageIds) {
1620
1623
  const containers = byPackage.get(packageId) ?? [];
1621
1624
  const selector = containers.length === 1 ? containers[0] : { package_id: packageId, selector_containers: containers };
1622
- const memoizedResolver = memoizePackageResolver(resolver);
1625
+ if (!packageResolvers.has(packageId)) packageResolvers.set(packageId, memoizePackageResolver(resolver));
1626
+ const memoizedResolver = packageResolvers.get(packageId);
1623
1627
  let creativeResolverRef;
1624
1628
  const packageResolver = memoizedResolver ? (context) => {
1625
1629
  const answer = memoizedResolver(context);
@@ -1630,6 +1634,10 @@ function projectAssignedCreative(creative, packageIds, selectors, converter, res
1630
1634
  try {
1631
1635
  const allCandidates = candidatesFromContainer(selector, packageResolver, "sync_creatives");
1632
1636
  knownCandidates = assignedLegacyCandidates(creative, selector, allCandidates);
1637
+ const available = knownCandidates.filter((candidate) => !candidate.canonicalOnly).map((candidate) => candidate.ref);
1638
+ sharedCandidates = sharedCandidates ? sharedCandidates.filter((ref2) => available.some((candidate) => sameLegacyIdentity(ref2, candidate))) : available.filter(
1639
+ (ref2, index) => available.findIndex((candidate) => sameLegacyIdentity(ref2, candidate)) === index
1640
+ );
1633
1641
  const missingSelectedMapping = allCandidates.length > 0 && knownCandidates.length === 0 && (optionReference(creative.format_option_ref) !== void 0 || selectedOptionReferences(selector).length > 0);
1634
1642
  if (invalidDuration && options?.playerSizedRefs === "omit_unstated_size")
1635
1643
  throw new CreativeFormatProjectionError(
@@ -1644,15 +1652,37 @@ function projectAssignedCreative(creative, packageIds, selectors, converter, res
1644
1652
  "the package forbids legacy creative formats"
1645
1653
  );
1646
1654
  }
1647
- let value = projectCreativeForDelivery(
1648
- selectionCreative,
1649
- selector,
1650
- "legacy",
1651
- "sync_creatives",
1652
- converter,
1653
- packageResolver,
1654
- definitions
1655
- );
1655
+ let value;
1656
+ if (sharedIdentity) {
1657
+ const canonical = canonicalizeCreative(selectionCreative, selector, "sync_creatives", converter);
1658
+ (0, import_legacy_metadata.transferLegacyCreativeMetadata)(selectionCreative, canonical);
1659
+ const ref2 = selectLegacyRef(
1660
+ legacyRef(selectionCreative.format_id) ? selectionCreative : canonical,
1661
+ selector,
1662
+ packageResolver,
1663
+ "sync_creatives",
1664
+ knownCandidates.filter(
1665
+ (candidate) => !candidate.canonicalOnly && sameLegacyIdentity(candidate.ref, sharedIdentity)
1666
+ )
1667
+ );
1668
+ if (!ref2)
1669
+ throw new CreativeFormatProjectionError(
1670
+ "sync_creatives",
1671
+ String(creative.creative_id),
1672
+ "the shared legacy format identity has no unambiguous compatible reference for this package"
1673
+ );
1674
+ value = projectCreative(canonical, ref2, definitions, "sync_creatives");
1675
+ } else {
1676
+ value = projectCreativeForDelivery(
1677
+ selectionCreative,
1678
+ selector,
1679
+ "legacy",
1680
+ "sync_creatives",
1681
+ converter,
1682
+ packageResolver,
1683
+ definitions
1684
+ );
1685
+ }
1656
1686
  if (selectionCreative !== creative) {
1657
1687
  const restored = { ...value };
1658
1688
  if (Object.hasOwn(creative, "format_parameters")) restored.format_parameters = creative.format_parameters;
@@ -1740,6 +1770,22 @@ function projectAssignedCreative(creative, packageIds, selectors, converter, res
1740
1770
  const reconciled = reconcileLegacyAssignmentRefs(resolved);
1741
1771
  if ("value" in reconciled) return reconciled.value;
1742
1772
  conflicts = reconciled.conflicts;
1773
+ if (!sharedIdentity && conflicts.some((conflict) => conflict.constraint === "format_id")) {
1774
+ const sharedValues = [];
1775
+ for (const identity of sharedCandidates ?? []) {
1776
+ try {
1777
+ sharedValues.push(
1778
+ projectAssignedCreative(creative, packageIds, selectors, converter, resolver, definitions, options, {
1779
+ identity,
1780
+ resolvers: packageResolvers
1781
+ })
1782
+ );
1783
+ } catch (error) {
1784
+ if (!(error instanceof CreativeFormatProjectionError)) throw error;
1785
+ }
1786
+ }
1787
+ if (sharedValues.length === 1) return sharedValues[0];
1788
+ }
1743
1789
  const refs = resolved.map((entry) => entry.ref);
1744
1790
  const first = refs[0];
1745
1791
  const statesSize = (value) => value !== void 0 && [
@@ -60,9 +60,10 @@ function stripLegacyCreativeIdentity(value) {
60
60
  const nonCreativeAgentContext = (key) => typeof key === "string" && !/(^|_)(?:creative|format|legacy)($|_)/.test(key) && /(^|_)(?:agents?|agent_details|agent_info)($|_)/.test(key);
61
61
  const nonCreativeSignalContext = (owner, key) => ownDataValue(owner, "source") === "agent" && typeof key === "string" && /(^|_)signal_ids?($|_)/.test(key);
62
62
  const nonCreativeListContext = (owner, key) => typeof ownDataValue(owner, "list_id") === "string" && typeof key === "string" && /(^|_)(?:property_list|collection_list|list_ref)($|_)/.test(key);
63
- const explicitNonCreativeContextKey = (key) => nonCreativeAgentContext(key) || typeof key === "string" && /(^|_)(?:signal_ids?|property_list|collection_list|list_ref)($|_)/.test(key);
63
+ const nonCreativeVerifierContext = (key) => key === "accepted_verifiers";
64
+ const explicitNonCreativeContextKey = (key) => nonCreativeAgentContext(key) || nonCreativeVerifierContext(key) || typeof key === "string" && /(^|_)(?:signal_ids?|property_list|collection_list|list_ref)($|_)/.test(key);
64
65
  const standaloneLegacyTuple = (owner, ownerKey) => {
65
- if (nonCreativeAgentContext(ownerKey) || nonCreativeSignalContext(owner, ownerKey) || nonCreativeListContext(owner, ownerKey)) {
66
+ if (nonCreativeAgentContext(ownerKey) || nonCreativeVerifierContext(ownerKey) || nonCreativeSignalContext(owner, ownerKey) || nonCreativeListContext(owner, ownerKey)) {
66
67
  return false;
67
68
  }
68
69
  if (typeof ownDataValue(owner, "agent_url") !== "string" || typeof ownDataValue(owner, "id") !== "string") {
@@ -73,7 +74,7 @@ function stripLegacyCreativeIdentity(value) {
73
74
  const preservesNonCreativeAgentUrl = (key, owner, ownerKey) => {
74
75
  if (!/(^|_)agent_url($|_)/.test(key)) return false;
75
76
  if (key === "agent_url") {
76
- return nonCreativeAgentContext(ownerKey) || nonCreativeSignalContext(owner, ownerKey) || nonCreativeListContext(owner, ownerKey) || typeof ownDataValue(owner, "id") === "string" && !standaloneLegacyTuple(owner, ownerKey);
77
+ return nonCreativeAgentContext(ownerKey) || nonCreativeVerifierContext(ownerKey) || nonCreativeSignalContext(owner, ownerKey) || nonCreativeListContext(owner, ownerKey) || typeof ownDataValue(owner, "id") === "string" && !standaloneLegacyTuple(owner, ownerKey);
77
78
  }
78
79
  return !/(^|_)(?:creative|format|legacy|offending|target|input|output)($|_)/.test(key);
79
80
  };
@@ -652,8 +653,7 @@ function preferMostConstrainedLegacyCandidates(candidates, creative) {
652
653
  const specific = remaining.filter((candidate) => legacyIdPinsDimensions(candidate.ref) === true);
653
654
  return specific.length > 0 && specific.length < remaining.length ? specific : remaining;
654
655
  }
655
- function selectLegacyRef(creative, container, canonicalFormatLegacyResolver, operation = "creative_delivery") {
656
- let candidates = candidatesFromContainer(container, canonicalFormatLegacyResolver, operation);
656
+ function selectLegacyRef(creative, container, canonicalFormatLegacyResolver, operation = "creative_delivery", candidates = candidatesFromContainer(container, canonicalFormatLegacyResolver, operation)) {
657
657
  const creativeOptionRef = optionReference(creative.format_option_ref);
658
658
  const selectedOptionRefs = Array.isArray(container.format_option_refs) ? container.format_option_refs.flatMap((value) => {
659
659
  const ref = optionReference(value);
@@ -1577,9 +1577,12 @@ function reconcileLegacyAssignmentRefs(resolved) {
1577
1577
  transferLegacyCreativeMetadata(source.value, value);
1578
1578
  return { value };
1579
1579
  }
1580
- function projectAssignedCreative(creative, packageIds, selectors, converter, resolver, definitions, options) {
1580
+ function projectAssignedCreative(creative, packageIds, selectors, converter, resolver, definitions, options, search) {
1581
+ const sharedIdentity = search?.identity;
1582
+ const packageResolvers = search?.resolvers ?? /* @__PURE__ */ new Map();
1581
1583
  const packageRefs = [];
1582
1584
  const resolved = [];
1585
+ let sharedCandidates;
1583
1586
  const parameterKeys = /* @__PURE__ */ new Set();
1584
1587
  let compatibleParameters = true;
1585
1588
  const playerSized = creative.format_kind === "video_vast" || creative.format_kind === "audio_vast";
@@ -1607,7 +1610,8 @@ function projectAssignedCreative(creative, packageIds, selectors, converter, res
1607
1610
  for (const packageId of packageIds) {
1608
1611
  const containers = byPackage.get(packageId) ?? [];
1609
1612
  const selector = containers.length === 1 ? containers[0] : { package_id: packageId, selector_containers: containers };
1610
- const memoizedResolver = memoizePackageResolver(resolver);
1613
+ if (!packageResolvers.has(packageId)) packageResolvers.set(packageId, memoizePackageResolver(resolver));
1614
+ const memoizedResolver = packageResolvers.get(packageId);
1611
1615
  let creativeResolverRef;
1612
1616
  const packageResolver = memoizedResolver ? (context) => {
1613
1617
  const answer = memoizedResolver(context);
@@ -1618,6 +1622,10 @@ function projectAssignedCreative(creative, packageIds, selectors, converter, res
1618
1622
  try {
1619
1623
  const allCandidates = candidatesFromContainer(selector, packageResolver, "sync_creatives");
1620
1624
  knownCandidates = assignedLegacyCandidates(creative, selector, allCandidates);
1625
+ const available = knownCandidates.filter((candidate) => !candidate.canonicalOnly).map((candidate) => candidate.ref);
1626
+ sharedCandidates = sharedCandidates ? sharedCandidates.filter((ref2) => available.some((candidate) => sameLegacyIdentity(ref2, candidate))) : available.filter(
1627
+ (ref2, index) => available.findIndex((candidate) => sameLegacyIdentity(ref2, candidate)) === index
1628
+ );
1621
1629
  const missingSelectedMapping = allCandidates.length > 0 && knownCandidates.length === 0 && (optionReference(creative.format_option_ref) !== void 0 || selectedOptionReferences(selector).length > 0);
1622
1630
  if (invalidDuration && options?.playerSizedRefs === "omit_unstated_size")
1623
1631
  throw new CreativeFormatProjectionError(
@@ -1632,15 +1640,37 @@ function projectAssignedCreative(creative, packageIds, selectors, converter, res
1632
1640
  "the package forbids legacy creative formats"
1633
1641
  );
1634
1642
  }
1635
- let value = projectCreativeForDelivery(
1636
- selectionCreative,
1637
- selector,
1638
- "legacy",
1639
- "sync_creatives",
1640
- converter,
1641
- packageResolver,
1642
- definitions
1643
- );
1643
+ let value;
1644
+ if (sharedIdentity) {
1645
+ const canonical = canonicalizeCreative(selectionCreative, selector, "sync_creatives", converter);
1646
+ transferLegacyCreativeMetadata(selectionCreative, canonical);
1647
+ const ref2 = selectLegacyRef(
1648
+ legacyRef(selectionCreative.format_id) ? selectionCreative : canonical,
1649
+ selector,
1650
+ packageResolver,
1651
+ "sync_creatives",
1652
+ knownCandidates.filter(
1653
+ (candidate) => !candidate.canonicalOnly && sameLegacyIdentity(candidate.ref, sharedIdentity)
1654
+ )
1655
+ );
1656
+ if (!ref2)
1657
+ throw new CreativeFormatProjectionError(
1658
+ "sync_creatives",
1659
+ String(creative.creative_id),
1660
+ "the shared legacy format identity has no unambiguous compatible reference for this package"
1661
+ );
1662
+ value = projectCreative(canonical, ref2, definitions, "sync_creatives");
1663
+ } else {
1664
+ value = projectCreativeForDelivery(
1665
+ selectionCreative,
1666
+ selector,
1667
+ "legacy",
1668
+ "sync_creatives",
1669
+ converter,
1670
+ packageResolver,
1671
+ definitions
1672
+ );
1673
+ }
1644
1674
  if (selectionCreative !== creative) {
1645
1675
  const restored = { ...value };
1646
1676
  if (Object.hasOwn(creative, "format_parameters")) restored.format_parameters = creative.format_parameters;
@@ -1728,6 +1758,22 @@ function projectAssignedCreative(creative, packageIds, selectors, converter, res
1728
1758
  const reconciled = reconcileLegacyAssignmentRefs(resolved);
1729
1759
  if ("value" in reconciled) return reconciled.value;
1730
1760
  conflicts = reconciled.conflicts;
1761
+ if (!sharedIdentity && conflicts.some((conflict) => conflict.constraint === "format_id")) {
1762
+ const sharedValues = [];
1763
+ for (const identity of sharedCandidates ?? []) {
1764
+ try {
1765
+ sharedValues.push(
1766
+ projectAssignedCreative(creative, packageIds, selectors, converter, resolver, definitions, options, {
1767
+ identity,
1768
+ resolvers: packageResolvers
1769
+ })
1770
+ );
1771
+ } catch (error) {
1772
+ if (!(error instanceof CreativeFormatProjectionError)) throw error;
1773
+ }
1774
+ }
1775
+ if (sharedValues.length === 1) return sharedValues[0];
1776
+ }
1731
1777
  const refs = resolved.map((entry) => entry.ref);
1732
1778
  const first = refs[0];
1733
1779
  const statesSize = (value) => value !== void 0 && [
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * AdCP SDK library version
3
3
  */
4
- export declare const LIBRARY_VERSION = "17.0.0-beta.13";
4
+ export declare const LIBRARY_VERSION = "17.0.0-beta.15";
5
5
  /**
6
6
  * AdCP specification version this library is built for
7
7
  */
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
33
33
  * Full version information
34
34
  */
35
35
  export declare const VERSION_INFO: {
36
- readonly library: "17.0.0-beta.13";
36
+ readonly library: "17.0.0-beta.15";
37
37
  readonly adcp: "3.3.0-beta.3";
38
38
  readonly compatibleVersions: readonly ["v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.1.25", "3.1.26", "3.1.27", "3.1.28", "3.1.29", "3.1.30", "3.1.31", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4", "3.2.5", "3.2.6", "3.2.7", "3.2.8", "3.3.0-beta.3", "3.3-beta.3"];
39
- readonly generatedAt: "2026-11-03T00:35:57.168Z";
39
+ readonly generatedAt: "2026-11-03T12:43:16.598Z";
40
40
  };
41
41
  /**
42
42
  * Get the AdCP specification version this library is built for
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * AdCP SDK library version
3
3
  */
4
- export declare const LIBRARY_VERSION = "17.0.0-beta.13";
4
+ export declare const LIBRARY_VERSION = "17.0.0-beta.15";
5
5
  /**
6
6
  * AdCP specification version this library is built for
7
7
  */
@@ -33,10 +33,10 @@ export type AdcpVersion = (typeof COMPATIBLE_ADCP_VERSIONS)[number];
33
33
  * Full version information
34
34
  */
35
35
  export declare const VERSION_INFO: {
36
- readonly library: "17.0.0-beta.13";
36
+ readonly library: "17.0.0-beta.15";
37
37
  readonly adcp: "3.3.0-beta.3";
38
38
  readonly compatibleVersions: readonly ["v3", "3.0.0", "3.0", "3.0.1", "3.0.2", "3.0.3", "3.0.4", "3.0.5", "3.0.6", "3.0.7", "3.0.8", "3.0.9", "3.0.10", "3.0.11", "3.0.12", "3.0.13", "3.0.14", "3.0.15", "3.0.16", "3.0.17", "3.0.18", "3.0.19", "3.0.20", "3.0.21", "3.0.22", "3.0.23", "3.0.24", "3.0.25", "3.1.0", "3.1", "3.1.1", "3.1.2", "3.1.3", "3.1.4", "3.1.5", "3.1.6", "3.1.7", "3.1.8", "3.1.9", "3.1.10", "3.1.11", "3.1.12", "3.1.13", "3.1.14", "3.1.15", "3.1.16", "3.1.17", "3.1.18", "3.1.19", "3.1.20", "3.1.21", "3.1.22", "3.1.23", "3.1.24", "3.1.25", "3.1.26", "3.1.27", "3.1.28", "3.1.29", "3.1.30", "3.1.31", "3.2.1", "3.2", "3.2.2", "3.2.3", "3.2.4", "3.2.5", "3.2.6", "3.2.7", "3.2.8", "3.3.0-beta.3", "3.3-beta.3"];
39
- readonly generatedAt: "2026-11-03T00:35:57.168Z";
39
+ readonly generatedAt: "2026-11-03T12:43:16.598Z";
40
40
  };
41
41
  /**
42
42
  * Get the AdCP specification version this library is built for
@@ -31,7 +31,7 @@ __export(version_exports, {
31
31
  toReleasePrecisionVersion: () => toReleasePrecisionVersion
32
32
  });
33
33
  module.exports = __toCommonJS(version_exports);
34
- const LIBRARY_VERSION = "17.0.0-beta.13";
34
+ const LIBRARY_VERSION = "17.0.0-beta.15";
35
35
  const ADCP_VERSION = "3.3.0-beta.3";
36
36
  const ADCP_MAJOR_VERSION = 3;
37
37
  const COMPATIBLE_ADCP_VERSIONS = [
@@ -109,10 +109,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
109
109
  "3.3-beta.3"
110
110
  ];
111
111
  const VERSION_INFO = {
112
- library: "17.0.0-beta.13",
112
+ library: "17.0.0-beta.15",
113
113
  adcp: "3.3.0-beta.3",
114
114
  compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
115
- generatedAt: "2026-11-03T00:35:57.168Z"
115
+ generatedAt: "2026-11-03T12:43:16.598Z"
116
116
  };
117
117
  function getAdcpVersion() {
118
118
  return ADCP_VERSION;
@@ -1,4 +1,4 @@
1
- const LIBRARY_VERSION = "17.0.0-beta.13";
1
+ const LIBRARY_VERSION = "17.0.0-beta.15";
2
2
  const ADCP_VERSION = "3.3.0-beta.3";
3
3
  const ADCP_MAJOR_VERSION = 3;
4
4
  const COMPATIBLE_ADCP_VERSIONS = [
@@ -76,10 +76,10 @@ const COMPATIBLE_ADCP_VERSIONS = [
76
76
  "3.3-beta.3"
77
77
  ];
78
78
  const VERSION_INFO = {
79
- library: "17.0.0-beta.13",
79
+ library: "17.0.0-beta.15",
80
80
  adcp: "3.3.0-beta.3",
81
81
  compatibleVersions: COMPATIBLE_ADCP_VERSIONS,
82
- generatedAt: "2026-11-03T00:35:57.168Z"
82
+ generatedAt: "2026-11-03T12:43:16.598Z"
83
83
  };
84
84
  function getAdcpVersion() {
85
85
  return ADCP_VERSION;
@@ -1,7 +1,7 @@
1
1
  # AdCP Type Summary
2
2
 
3
3
  > Generated at: 2026-11-03
4
- > @adcp/sdk v17.0.0-beta.13
4
+ > @adcp/sdk v17.0.0-beta.15
5
5
 
6
6
  Curated reference of the types that matter for using the AdCP client. For full generated types see `src/lib/types/tools.generated.ts` and `src/lib/types/core.generated.ts`.
7
7
 
@@ -0,0 +1,56 @@
1
+ # Selecting a complete brand entry
2
+
3
+ The registry can return the complete resolved brand entry as `ResolvedBrand.brand`. It retains brand.json's field shapes, including locale-keyed names and taglines, the fonts object, colors, and tone. It comes from the same winning identity source as the rest of that response. The existing `brand_manifest` field remains available with its existing meaning.
4
+
5
+ ```typescript
6
+ import { RegistryClient } from '@adcp/sdk';
7
+
8
+ const registry = new RegistryClient();
9
+ const resolved = await registry.lookupBrand('spark.example');
10
+ const entry = resolved?.brand;
11
+ if (entry) {
12
+ console.log(entry.names, entry.fonts, entry.tone);
13
+ }
14
+ ```
15
+
16
+ Older registry deployments can omit this field. It is also absent when the selected source cannot supply a unique, complete entry. Absence is not permission to choose the first brand in a portfolio or to mix an entry from a different source with the selected response's metadata.
17
+
18
+ For a cached registry response, helper output must also agree with the registry's established brand identity. The registry can omit `brand` when its existing identity and the document's unique match disagree. Use an independently established portfolio `brandId` when available, and retain absence when identity agreement cannot be established.
19
+
20
+ For a document that you independently fetched or cached, use the pure helper:
21
+
22
+ ```typescript
23
+ import { selectBrandEntry } from '@adcp/sdk/brand';
24
+
25
+ const cachedDocument = {
26
+ house: { domain: 'nova-brands.example', name: 'Nova Brands' },
27
+ brands: [
28
+ { id: 'glow', names: [{ en: 'Glow' }] },
29
+ {
30
+ id: 'spark',
31
+ names: [{ en: 'Spark' }],
32
+ properties: [{ type: 'website', identifier: 'spark.example' }],
33
+ },
34
+ ],
35
+ };
36
+
37
+ const entry = selectBrandEntry(cachedDocument, 'spark.example');
38
+ const byId = selectBrandEntry(cachedDocument, {
39
+ domain: 'nova-brands.example',
40
+ brandId: 'spark',
41
+ });
42
+ ```
43
+
44
+ The helper is also exported from `@adcp/sdk` and `@adcp/sdk/client`.
45
+
46
+ Selection rules match the registry's entry projection:
47
+
48
+ - A canonical `id` + `names` document supplies the brand document itself.
49
+ - A known `brandId` selects that unique inline portfolio entry; it is an ID, not a display name.
50
+ - Otherwise an entry must uniquely match the requested hostname through its homepage URL or an owned website property. The canonical brand.json field is `relationship`, with an omitted relationship defaulting to `owned`; `direct`, `delegated`, and `ad_network` properties do not select identity. A supplied `delegation_type` compatibility field also prevents an owned-property match, even alongside `relationship: 'owned'`.
51
+ - On the house's own hostname, a unique `master` is the default. A sole inline brand may supply the default only when no pointer brands exist. Other hostnames do not inherit this default. `houseDomains` admits only extra hostnames you have already confirmed through the protocol's permitted HTTPS normalization path.
52
+ - Missing/ambiguous entries, pointer-only documents, redirects, and agent-only documents return `undefined`. There is no first-entry fallback.
53
+
54
+ The function performs no fetching, schema validation, or ownership verification. It does not follow house redirects, `authoritative_location`, or `brand_refs[]`; callers resolving those documents retain responsibility for their transport and trust rules. Its output preserves extension fields while excluding historical ephemeral `brand_context`, and it does not modify the input document.
55
+
56
+ An entry is identity data, not authorization evidence. Apply the registry's provenance and relationship-trust rules independently, and validate field shapes with the protocol's canonical schemas when needed.