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

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 (70) 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-owned-task.d.mts +3 -0
  37. package/dist/lib/testing/storyboard/runner-owned-task.d.ts +3 -0
  38. package/dist/lib/testing/storyboard/runner-owned-task.js +38 -0
  39. package/dist/lib/testing/storyboard/runner-owned-task.mjs +13 -0
  40. package/dist/lib/testing/storyboard/runner.d.mts +1 -42
  41. package/dist/lib/testing/storyboard/runner.d.ts +1 -42
  42. package/dist/lib/testing/storyboard/runner.js +14 -47
  43. package/dist/lib/testing/storyboard/runner.mjs +6 -39
  44. package/dist/lib/testing/storyboard/seeding.js +169 -2
  45. package/dist/lib/testing/storyboard/seeding.mjs +169 -2
  46. package/dist/lib/testing/storyboard/types.d.mts +4 -2
  47. package/dist/lib/testing/storyboard/types.d.ts +4 -2
  48. package/dist/lib/testing/storyboard/types.js +1 -0
  49. package/dist/lib/testing/storyboard/types.mjs +1 -0
  50. package/dist/lib/testing/storyboard/validations.d.mts +1 -1
  51. package/dist/lib/testing/storyboard/validations.d.ts +1 -1
  52. package/dist/lib/testing/storyboard/validations.js +60 -1
  53. package/dist/lib/testing/storyboard/validations.mjs +61 -1
  54. package/dist/lib/testing/storyboard/webhook-assertions.js +10 -9
  55. package/dist/lib/testing/storyboard/webhook-assertions.mjs +11 -10
  56. package/dist/lib/v2/projection/creative-delivery.js +62 -16
  57. package/dist/lib/v2/projection/creative-delivery.mjs +62 -16
  58. package/dist/lib/version.d.mts +3 -3
  59. package/dist/lib/version.d.ts +3 -3
  60. package/dist/lib/version.js +3 -3
  61. package/dist/lib/version.mjs +3 -3
  62. package/docs/TYPE-SUMMARY.md +1 -1
  63. package/docs/guides/BRAND-ENTRY-SELECTION.md +56 -0
  64. package/docs/guides/REPORTING-LEDGER.md +142 -12
  65. package/docs/guides/REPORTING-OPERATIONS.md +18 -5
  66. package/docs/guides/VALIDATE-YOUR-AGENT.md +44 -0
  67. package/docs/llms.txt +1 -1
  68. package/docs/migration-14.x-rc-worksheet.md +4 -4
  69. package/docs/migration-reporting-row-storage-alignment.md +4 -2
  70. package/package.json +1 -1
@@ -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.16";
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.16";
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-03T17:30:06.582Z";
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.16";
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.16";
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-03T17:30:06.582Z";
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.16";
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.16",
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-03T17:30:06.582Z"
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.16";
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.16",
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-03T17:30:06.582Z"
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.16
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.
@@ -744,16 +744,71 @@ await store.readyRowStorage();
744
744
  several row sets. Every delete path (period retirement, compaction and the
745
745
  intent sweep) therefore skips an object while a live row set outside the
746
746
  operation still references the same binding, key and native version, or an
747
- open write intent created it. (With unique keys, a create-only write only
748
- finds an existing object when a writer retries the same row set.) The check
749
- and delete run under the per-object lock described below. The reference check and the delete run in one
750
- transaction under a per-object advisory lock, and a commit that adopts an
751
- existing object takes the same lock, proves the object is still there and
752
- holds the lock until its chunk rows commit. A delete that wins the lock makes the adopting
753
- commit fail with `STATE_UNAVAILABLE` (the writer re-uploads once its intent
754
- lapses); a commit that wins is seen by the delete, which skips. A skipped
755
- object is deleted by the retirement, compaction or sweep of the last row set
756
- that referenced it, so it is not leaked.
747
+ open write intent created it. With unique keys, a create-only write only
748
+ finds an existing object when a writer retries the same row set.
749
+ - **Object deletes and commits take no per-object lock, with one exception.**
750
+ Retirement, compaction and the intent sweep run the reference check as a
751
+ plain query, then delete the exact native version, holding no transaction or
752
+ pooled connection across the provider call. They are safe without a lock
753
+ because of five fences, none of which is the lock:
754
+ 1. Every writable key includes `{revision_key}` (a SHA-256 of the row set ID)
755
+ and `{content_sha256}`, so one row set alone can ever name a key through a
756
+ writable binding. A committed row set is replayed: a late writer that
757
+ passed the replay check can adopt its just-committed object, but its
758
+ commit inserts nothing (the row set exists), so it cannot reference an
759
+ object a retirement or compaction then deletes. A `readOnly` binding's old
760
+ template can map several row sets to one object, but nothing adopts through
761
+ it; there the reference check and fence 4 are the whole argument. Bindings
762
+ that share one bucket and prefix must route a row set to one binding across
763
+ attempts, because the reference check is per binding (the orphan collector
764
+ checks every binding).
765
+ 2. A header-only revision's commit holds the account lock and `FOR SHARE`-locks
766
+ a predecessor that must still be `live`. Retirement and compaction mark a
767
+ row set `pruning` under the same account lock before they delete anything,
768
+ and a `pruning` row set neither counts as a reference nor can be shared. So
769
+ a sharer commits first (its chunk rows then make the delete skip) or fails
770
+ with `STATE_UNAVAILABLE` and re-uploads under its own key.
771
+ 3. The intent sweep moves an expired `open` intent to `sweeping` under the
772
+ account lock; a writer closes that intent, still `open`, in the commit
773
+ transaction that inserts its chunk rows. Exactly one wins, so a writer past
774
+ its lease cannot commit objects the sweep deletes, and a retry cannot take
775
+ over an intent being swept. A takeover renews the expiry, so the sweep
776
+ cannot claim it.
777
+ 4. Concurrent retirements and compactions count only row sets that are not
778
+ `pruning`, each after committing its own `pruning` state, so at least one
779
+ of any two deletes a shared object and none can both skip it.
780
+ 5. Deletes name an exact native version, so one cannot remove an object
781
+ re-created at the same key. This needs write-unique native versions, a
782
+ provider requirement the conformance check `write-unique-version` tests.
783
+
784
+ The advisory lock `adcp-reporting-object:{binding_id}:{object_ref}` stays in
785
+ two places that pair with each other, because nothing else orders them. A
786
+ commit that adopts an object its own intent did not record (an earlier
787
+ attempt's `PUT` landed before the intent recorded it, or a writer created it
788
+ after a takeover) takes the lock, in key order, before it proves the object with
789
+ a version-pinned `stat`, and holds it until its chunk rows commit. An object its own intent recorded takes
790
+ no lock: until the transaction commits, the open intent names it. The orphan
791
+ collector deletes only objects no record names, so each of its deletes takes
792
+ the lock of every binding (they can share a bucket and prefix), repeats the
793
+ reference check under it, and then deletes. A collector that wins makes the
794
+ adopting commit fail its version-pinned `stat` with `STATE_UNAVAILABLE` (the
795
+ writer re-uploads once its intent lapses); a commit that wins is seen by the
796
+ collector, which skips. The collector's clone fence is a separate protection:
797
+ an advisory lock is per database and cannot order a clone against the
798
+ original. A skipped object is deleted by the retirement, compaction or sweep
799
+ of the last row set that referenced it, so it is not leaked.
800
+ - **Cross-SDK contract.** A ledger database has one writer SDK (the design record's
801
+ §5), so the Python and JavaScript SDKs need not agree on a lock to coexist; this
802
+ is the intended contract for both, with the same key text. The Python side
803
+ (adcp-client-python#1492) mirrors it: (1) the delete paths above take no object lock; (2) the key text
804
+ is `adcp-reporting-object:` + binding ID + `:` + object ref, hashed with
805
+ `hashtextextended(text, 0)` for `pg_advisory_xact_lock`; (3) an adopting commit
806
+ locks only adopted objects absent from its own intent's `created_objects`
807
+ (matching on object ref and native version), in object-ref order, after the
808
+ account lock and after closing its intent, then proves each adopted object with
809
+ a version-pinned `stat`; (4) the orphan collector locks every binding's key for
810
+ the object, sorted by binding ID, in the transaction that repeats the
811
+ reference check and deletes. Lock order is account lock, then object locks.
757
812
  - An upload runs only while the obligation lease still covers
758
813
  `writeDeadlineMilliseconds` plus five seconds. A fenced write intent records
759
814
  every object the upload created, and the ledger commit closes the intent in
@@ -780,7 +835,7 @@ await store.readyRowStorage();
780
835
  absent, without reading the body. The commit transaction uses it to prove an
781
836
  adopted object is unchanged (native versions are write-unique, so the same
782
837
  version at the recorded size is the same bytes) instead of downloading it
783
- while holding the account and object locks. A provider without `stat` falls
838
+ while holding the account lock. A provider without `stat` falls
784
839
  back to reading the whole object there. All bundled providers implement it.
785
840
  Also implement the optional `list({ prefix, pageToken, pageSize })`, which
786
841
  returns `{ objects: [{ objectRef, nativeVersionRef, sizeBytes, createdAt }],
@@ -1309,6 +1364,80 @@ setInterval(() => {
1309
1364
  }, 15 * 60_000);
1310
1365
  ```
1311
1366
 
1367
+ #### The two-table contract
1368
+
1369
+ The sink writes two tables, and the second is part of its contract. The rows
1370
+ table holds the report rows. The **revisions table** holds one metadata line per
1371
+ revision: `reporting_revision_id`, `reporting_obligation_id`, `account_id`,
1372
+ `revision_number`, `finality`, `period_date`, `supersedes_reporting_revision_id`,
1373
+ `period_start`, `period_end`, `source_timezone`, `observed_at`, `data_through`,
1374
+ `revision_content_sha256`, `row_count` and `control_totals`. The reference DDL
1375
+ (`sink.defaultTablesSql`) declares exactly these columns, and a test pins the
1376
+ DDL to what the sink loads. The `current_rows` view picks each obligation's
1377
+ current revision from the revisions table, so the rows table alone cannot tell
1378
+ you which revision is current.
1379
+
1380
+ - **The revisions table is required.** `revisionsTableId` has no default and no
1381
+ way to turn it off, and the sink refuses to start without it. A custom table
1382
+ must keep every column above: the load sets no schema and no
1383
+ `ignoreUnknownValues`, so a missing column fails the revisions job (and only
1384
+ that job: the rows job ran first and has already landed).
1385
+ - **Load order.** Each batch loads the rows table first, then the revisions table,
1386
+ as two separate load jobs. BigQuery has no transaction across tables. The
1387
+ cursor advances only after both jobs have finished cleanly.
1388
+ - **Visibility.** A revision's rows can be visible in the rows table before its
1389
+ metadata is in the revisions table: between the two jobs of a batch, and for as
1390
+ long as the revisions load keeps failing. `current_rows` shows only revisions
1391
+ whose metadata has loaded. While a newer revision's metadata is pending, each
1392
+ affected obligation keeps showing its previous revision, and an obligation
1393
+ whose first revision is pending shows nothing. The reverse does not happen
1394
+ through the sink: a revisions row implies its rows landed, because the rows job
1395
+ finished before the revisions job was submitted (so long as nothing outside the
1396
+ sink deletes or truncates the tables, which adopter-managed table retention
1397
+ can). Read the two tables in one query (the view does), or read the revisions
1398
+ table first.
1399
+ - **What to query.** For current figures, query `current_rows`. For revision
1400
+ history and audit, query the revisions table and join it to the rows table on
1401
+ `reporting_revision_id`. Do not sum the rows table alone: it holds every loaded
1402
+ revision, and cumulative snapshots double-count. To alert on metadata that is
1403
+ lagging, look for rows with no revisions row:
1404
+
1405
+ ```sql
1406
+ SELECT DISTINCT r.reporting_revision_id
1407
+ FROM `analytics-prod.reporting.media_buy_delivery_rows` AS r
1408
+ LEFT JOIN `analytics-prod.reporting.media_buy_delivery_revisions` AS v USING (reporting_revision_id)
1409
+ WHERE v.reporting_revision_id IS NULL
1410
+ ```
1411
+
1412
+ A non-empty result for a few minutes is the window between the two jobs. One
1413
+ that persists means the revisions load is failing (add a `period_date` filter
1414
+ to bound the scan on large tables).
1415
+ - **Recovery when the revisions load fails.** The batch plan stays in PostgreSQL
1416
+ and the cursor does not move, so nothing is lost and nothing needs editing by
1417
+ hand. The next `runOnce()` finds the rows job by its ID, accepts it as loaded
1418
+ and does not upload it again, then retries only the revisions job. A network
1419
+ error or timeout retries under the same job ID (BigQuery may have created the
1420
+ job, and the sink looks it up before it uploads). A job BigQuery ran and
1421
+ rejected is retried under a new attempt suffix: the run that first sees the
1422
+ failed job advances the attempt and rejects, and the run after it submits. A
1423
+ load job is atomic, so a failed one lands nothing and the rows are never
1424
+ duplicated. Fix the cause (usually a column the revisions table lacks), keep
1425
+ running, and `current_rows` catches up on its own. Do not insert or delete
1426
+ warehouse rows to repair it, and do not `reset()`: a reset reloads the history
1427
+ and duplicates it unless you empty the tables first. The exception is a failure
1428
+ that outlasts `maxFeedHoldDays`: change retention then stops waiting for the
1429
+ sink, and `runOnce()` reports the retired revisions as `missing` and loads no
1430
+ metadata for them. Their rows, already loaded, stay in the rows table with no
1431
+ revisions row (so the anti-join above keeps returning them and they never
1432
+ appear in `current_rows`); backfill their metadata or delete those rows by
1433
+ `reporting_revision_id`.
1434
+ - **Why the loader is custom.** The alternative is an Iceberg or Delta Lake table
1435
+ behind the object-storage interface, which BigQuery reads as an external table.
1436
+ That path carries no revisions table and no `current_rows` view, so an adopter
1437
+ who takes it owns the leaf-revision query.
1438
+
1439
+ #### How a run loads
1440
+
1312
1441
  - Each run follows the change feed and reads every revision's rows through the
1313
1442
  store's verified reader. It loads rows first and revision metadata second,
1314
1443
  in one load job per table per tick. The sink always adds
@@ -1445,7 +1574,8 @@ setInterval(() => {
1445
1574
  Do not discard the plan automatically: its load jobs may have succeeded.
1446
1575
  - Query `current_rows`, not the raw rows table. Pacing snapshots are
1447
1576
  cumulative, so summing across revisions double-counts. The view keeps each
1448
- obligation's current revision.
1577
+ obligation's current revision, read from the revisions table (see
1578
+ "The two-table contract" above for what is visible while that table lags).
1449
1579
  - The sink registers as a change-feed consumer, so `pruneChanges` keeps changes
1450
1580
  it has not loaded yet, and `retireExpiredPeriods` keeps the periods it has not
1451
1581
  loaded yet, in both cases only while its cursor was saved within