@adcp/sdk 17.0.0-beta.29 → 17.0.0-beta.30

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 (34) hide show
  1. package/dist/lib/reporting/ledger/handler.d.mts +4 -4
  2. package/dist/lib/reporting/ledger/handler.d.ts +4 -4
  3. package/dist/lib/reporting/ledger/handler.js +22 -5
  4. package/dist/lib/reporting/ledger/handler.mjs +22 -5
  5. package/dist/lib/reporting/ledger/producer.js +85 -10
  6. package/dist/lib/reporting/ledger/producer.mjs +85 -10
  7. package/dist/lib/reporting/ledger/types.d.mts +12 -1
  8. package/dist/lib/reporting/ledger/types.d.ts +12 -1
  9. package/dist/lib/reporting/service/index.d.mts +2 -1
  10. package/dist/lib/reporting/service/index.d.ts +2 -1
  11. package/dist/lib/reporting/service/index.js +37 -5
  12. package/dist/lib/reporting/service/index.mjs +37 -5
  13. package/dist/lib/reporting/source/fixtures.d.mts +4 -0
  14. package/dist/lib/reporting/source/fixtures.d.ts +4 -0
  15. package/dist/lib/reporting/source/inline.d.mts +5 -0
  16. package/dist/lib/reporting/source/inline.d.ts +5 -0
  17. package/dist/lib/reporting/source/inline.js +93 -13
  18. package/dist/lib/reporting/source/inline.mjs +93 -13
  19. package/dist/lib/reporting/source/schemas/reporting-source-slice-request-v1.json +24 -0
  20. package/dist/lib/reporting/source/source.d.mts +8 -0
  21. package/dist/lib/reporting/source/source.d.ts +8 -0
  22. package/dist/lib/reporting/source/source.js +18 -0
  23. package/dist/lib/reporting/source/source.mjs +18 -0
  24. package/dist/lib/testing/storyboard/validations.d.mts +1 -1
  25. package/dist/lib/testing/storyboard/validations.d.ts +1 -1
  26. package/dist/lib/version.d.mts +3 -3
  27. package/dist/lib/version.d.ts +3 -3
  28. package/dist/lib/version.js +3 -3
  29. package/dist/lib/version.mjs +3 -3
  30. package/docs/TYPE-SUMMARY.md +5 -3
  31. package/docs/guides/REPORTING-SOURCE-EXECUTOR.md +9 -1
  32. package/docs/llms.txt +1 -1
  33. package/docs/migration-14.x-rc-worksheet.md +4 -4
  34. package/package.json +1 -1
@@ -112,9 +112,9 @@ export declare function aggregateReportingCoverageV1(values: ReportingLedgerCove
112
112
  partially_covered_media_buy_ids: string[];
113
113
  unsupported_media_buy_ids: string[];
114
114
  unknown_media_buy_ids: string[];
115
- package_ids: never[];
116
- covered_package_ids: never[];
117
- unsupported_package_ids: never[];
118
- unknown_package_ids: never[];
115
+ package_ids: string[];
116
+ covered_package_ids: string[];
117
+ unsupported_package_ids: string[];
118
+ unknown_package_ids: string[];
119
119
  limitations: never[];
120
120
  };
@@ -112,9 +112,9 @@ export declare function aggregateReportingCoverageV1(values: ReportingLedgerCove
112
112
  partially_covered_media_buy_ids: string[];
113
113
  unsupported_media_buy_ids: string[];
114
114
  unknown_media_buy_ids: string[];
115
- package_ids: never[];
116
- covered_package_ids: never[];
117
- unsupported_package_ids: never[];
118
- unknown_package_ids: never[];
115
+ package_ids: string[];
116
+ covered_package_ids: string[];
117
+ unsupported_package_ids: string[];
118
+ unknown_package_ids: string[];
119
119
  limitations: never[];
120
120
  };
@@ -884,10 +884,10 @@ function wireCoverage(coverage) {
884
884
  partially_covered_media_buy_ids: coverage.partiallyCoveredMediaBuyIds,
885
885
  unsupported_media_buy_ids: coverage.unsupportedMediaBuyIds,
886
886
  unknown_media_buy_ids: coverage.unknownMediaBuyIds,
887
- package_ids: [],
888
- covered_package_ids: [],
889
- unsupported_package_ids: [],
890
- unknown_package_ids: [],
887
+ package_ids: coverage.packageIds ?? [],
888
+ covered_package_ids: coverage.coveredPackageIds ?? [],
889
+ unsupported_package_ids: coverage.unsupportedPackageIds ?? [],
890
+ unknown_package_ids: coverage.unknownPackageIds ?? [],
891
891
  limitations: []
892
892
  };
893
893
  }
@@ -933,6 +933,19 @@ function aggregateReportingCoverageV1(values, asOf) {
933
933
  const full = ids.filter((id) => isCovered(id) && !isUncovered(id));
934
934
  const unknown = ids.filter((id) => !isCovered(id) && unknownCandidates.has(id));
935
935
  const unsupported = ids.filter((id) => !isCovered(id) && !unknownCandidates.has(id) && unsupportedCandidates.has(id));
936
+ const packageIds = [...new Set(values.flatMap((value) => value.packageIds ?? []))].sort();
937
+ const coveredPackageCandidates = new Set(values.flatMap((value) => value.coveredPackageIds ?? []));
938
+ const unsupportedPackageCandidates = new Set(values.flatMap((value) => value.unsupportedPackageIds ?? []));
939
+ const unknownPackageCandidates = new Set(values.flatMap((value) => value.unknownPackageIds ?? []));
940
+ const coveredPackageIds = packageIds.filter(
941
+ (id) => coveredPackageCandidates.has(id) && !unsupportedPackageCandidates.has(id) && !unknownPackageCandidates.has(id)
942
+ );
943
+ const unsupportedPackageIds = packageIds.filter(
944
+ (id) => !coveredPackageCandidates.has(id) && unsupportedPackageCandidates.has(id) && !unknownPackageCandidates.has(id)
945
+ );
946
+ const coveredPackageSet = new Set(coveredPackageIds);
947
+ const unsupportedPackageSet = new Set(unsupportedPackageIds);
948
+ const unknownPackageIds = packageIds.filter((id) => !coveredPackageSet.has(id) && !unsupportedPackageSet.has(id));
936
949
  const status = values.every((value) => value.status === "full") ? "full" : full.length || partial.length ? "partial" : unknown.length ? "unknown" : "none";
937
950
  return wireCoverage({
938
951
  status,
@@ -941,7 +954,11 @@ function aggregateReportingCoverageV1(values, asOf) {
941
954
  fullyCoveredMediaBuyIds: full,
942
955
  partiallyCoveredMediaBuyIds: partial,
943
956
  unsupportedMediaBuyIds: unsupported,
944
- unknownMediaBuyIds: unknown
957
+ unknownMediaBuyIds: unknown,
958
+ packageIds,
959
+ coveredPackageIds,
960
+ unsupportedPackageIds,
961
+ unknownPackageIds
945
962
  });
946
963
  }
947
964
  function aggregateDataThrough(selected) {
@@ -871,10 +871,10 @@ function wireCoverage(coverage) {
871
871
  partially_covered_media_buy_ids: coverage.partiallyCoveredMediaBuyIds,
872
872
  unsupported_media_buy_ids: coverage.unsupportedMediaBuyIds,
873
873
  unknown_media_buy_ids: coverage.unknownMediaBuyIds,
874
- package_ids: [],
875
- covered_package_ids: [],
876
- unsupported_package_ids: [],
877
- unknown_package_ids: [],
874
+ package_ids: coverage.packageIds ?? [],
875
+ covered_package_ids: coverage.coveredPackageIds ?? [],
876
+ unsupported_package_ids: coverage.unsupportedPackageIds ?? [],
877
+ unknown_package_ids: coverage.unknownPackageIds ?? [],
878
878
  limitations: []
879
879
  };
880
880
  }
@@ -920,6 +920,19 @@ function aggregateReportingCoverageV1(values, asOf) {
920
920
  const full = ids.filter((id) => isCovered(id) && !isUncovered(id));
921
921
  const unknown = ids.filter((id) => !isCovered(id) && unknownCandidates.has(id));
922
922
  const unsupported = ids.filter((id) => !isCovered(id) && !unknownCandidates.has(id) && unsupportedCandidates.has(id));
923
+ const packageIds = [...new Set(values.flatMap((value) => value.packageIds ?? []))].sort();
924
+ const coveredPackageCandidates = new Set(values.flatMap((value) => value.coveredPackageIds ?? []));
925
+ const unsupportedPackageCandidates = new Set(values.flatMap((value) => value.unsupportedPackageIds ?? []));
926
+ const unknownPackageCandidates = new Set(values.flatMap((value) => value.unknownPackageIds ?? []));
927
+ const coveredPackageIds = packageIds.filter(
928
+ (id) => coveredPackageCandidates.has(id) && !unsupportedPackageCandidates.has(id) && !unknownPackageCandidates.has(id)
929
+ );
930
+ const unsupportedPackageIds = packageIds.filter(
931
+ (id) => !coveredPackageCandidates.has(id) && unsupportedPackageCandidates.has(id) && !unknownPackageCandidates.has(id)
932
+ );
933
+ const coveredPackageSet = new Set(coveredPackageIds);
934
+ const unsupportedPackageSet = new Set(unsupportedPackageIds);
935
+ const unknownPackageIds = packageIds.filter((id) => !coveredPackageSet.has(id) && !unsupportedPackageSet.has(id));
923
936
  const status = values.every((value) => value.status === "full") ? "full" : full.length || partial.length ? "partial" : unknown.length ? "unknown" : "none";
924
937
  return wireCoverage({
925
938
  status,
@@ -928,7 +941,11 @@ function aggregateReportingCoverageV1(values, asOf) {
928
941
  fullyCoveredMediaBuyIds: full,
929
942
  partiallyCoveredMediaBuyIds: partial,
930
943
  unsupportedMediaBuyIds: unsupported,
931
- unknownMediaBuyIds: unknown
944
+ unknownMediaBuyIds: unknown,
945
+ packageIds,
946
+ coveredPackageIds,
947
+ unsupportedPackageIds,
948
+ unknownPackageIds
932
949
  });
933
950
  }
934
951
  function aggregateDataThrough(selected) {
@@ -602,6 +602,7 @@ function createReportingProducer(options) {
602
602
  obligation,
603
603
  await readManifestRows(options.source, obligation, manifest, executionSignal, settlementGrace)
604
604
  );
605
+ assertRowsWithinFrozenPackageCoverage(obligation, rows);
605
606
  validateManifestFinalityForObligation(obligation, manifest);
606
607
  if (previous.some((value) => value.finality === "official")) {
607
608
  const official = previous.find((value) => value.finality === "official");
@@ -760,6 +761,7 @@ function planObligation(configuration, periodOrdinal, createdAt) {
760
761
  periodOrdinal,
761
762
  period: { start: new Date(start).toISOString(), end: new Date(end).toISOString() },
762
763
  constituents: configuration.constituents,
764
+ ...configuration.packageBindings?.length ? { packageBindings: configuration.packageBindings } : {},
763
765
  coverageRequirement: "full"
764
766
  };
765
767
  const semanticFingerprint = prefixedDigest(semantic);
@@ -792,12 +794,23 @@ function planObligation(configuration, periodOrdinal, createdAt) {
792
794
  fullyCoveredMediaBuyIds: [...configuration.mediaBuyIds].sort(),
793
795
  partiallyCoveredMediaBuyIds: [],
794
796
  unsupportedMediaBuyIds: [],
795
- unknownMediaBuyIds: []
797
+ unknownMediaBuyIds: [],
798
+ ...configuration.packageBindings?.length ? {
799
+ packageIds: [
800
+ ...new Set(configuration.constituents.flatMap((value) => value.packageId ? [value.packageId] : []))
801
+ ].sort(),
802
+ coveredPackageIds: [
803
+ ...new Set(configuration.constituents.flatMap((value) => value.packageId ? [value.packageId] : []))
804
+ ].sort(),
805
+ unsupportedPackageIds: [],
806
+ unknownPackageIds: []
807
+ } : {}
796
808
  },
797
809
  requestedMetrics: [...configuration.requestedMetrics],
798
810
  requestedDimensions: [...configuration.requestedDimensions],
799
811
  constituents: structuredClone(configuration.constituents),
800
812
  mediaBuyIds: [...configuration.mediaBuyIds].sort(),
813
+ ...configuration.packageBindings?.length ? { packageBindings: structuredClone(configuration.packageBindings) } : {},
801
814
  sourceSettings: structuredClone(configuration.sourceSettings),
802
815
  contract: structuredClone(configuration.contract),
803
816
  expectedAt: new Date(expectedAt).toISOString(),
@@ -821,7 +834,8 @@ function subscriptionConfiguration(input, plan, installedAt) {
821
834
  "historyStartOrdinal",
822
835
  "owedSet",
823
836
  "constituents",
824
- "mediaBuyIds"
837
+ "mediaBuyIds",
838
+ "packageBindings"
825
839
  ]) {
826
840
  if (Object.hasOwn(input, field)) {
827
841
  throw new TypeError(`Subscription configuration input must not supply ${field}`);
@@ -893,6 +907,15 @@ function planOwedSetObligation(configuration, input, offering, owedThroughMs, cr
893
907
  if (!sameMembers(mediaBuyIds, [...new Set(constituents.map((value) => value.mediaBuyId).filter(Boolean))])) {
894
908
  throw new Error("Subscription obligation media buys must equal its constituent denominator");
895
909
  }
910
+ const packageBindings = structuredClone(input.packageBindings ?? []);
911
+ const packageConstituentIds = new Set(
912
+ constituents.filter((value) => value.constituentKind === "package_item").map((value) => value.constituentId)
913
+ );
914
+ if (packageBindings.length !== packageConstituentIds.size || new Set(packageBindings.map((value) => value.constituentId)).size !== packageBindings.length || packageBindings.some(
915
+ (value) => !packageConstituentIds.has(value.constituentId) || !mediaBuyIds.includes(value.mediaBuyId)
916
+ )) {
917
+ throw new TypeError("Subscription obligation package bindings must match its authorized constituents");
918
+ }
896
919
  const listedProducts = (0, import_applicability.listedReportingSourceProductIdsV1)(offering.applicability);
897
920
  if (listedProducts !== void 0 && constituents.some((value) => !listedProducts.includes(value.productId))) {
898
921
  throw new Error("Reporting constituent product is outside its offering applicability");
@@ -912,6 +935,7 @@ function planOwedSetObligation(configuration, input, offering, owedThroughMs, cr
912
935
  period: { start: periodStart, end: periodEnd },
913
936
  constituents,
914
937
  mediaBuyIds,
938
+ ...packageBindings.length ? { packageBindings } : {},
915
939
  coverageRequirement: "full"
916
940
  };
917
941
  return {
@@ -940,12 +964,21 @@ function planOwedSetObligation(configuration, input, offering, owedThroughMs, cr
940
964
  fullyCoveredMediaBuyIds: [...mediaBuyIds],
941
965
  partiallyCoveredMediaBuyIds: [],
942
966
  unsupportedMediaBuyIds: [],
943
- unknownMediaBuyIds: []
967
+ unknownMediaBuyIds: [],
968
+ ...packageBindings.length ? {
969
+ packageIds: [...new Set(constituents.flatMap((value) => value.packageId ? [value.packageId] : []))].sort(),
970
+ coveredPackageIds: [
971
+ ...new Set(constituents.flatMap((value) => value.packageId ? [value.packageId] : []))
972
+ ].sort(),
973
+ unsupportedPackageIds: [],
974
+ unknownPackageIds: []
975
+ } : {}
944
976
  },
945
977
  requestedMetrics: [...configuration.requestedMetrics],
946
978
  requestedDimensions: [...configuration.requestedDimensions],
947
979
  constituents,
948
980
  mediaBuyIds,
981
+ ...packageBindings.length ? { packageBindings } : {},
949
982
  sourceSettings: structuredClone(configuration.sourceSettings),
950
983
  contract: structuredClone(configuration.contract),
951
984
  expectedAt: new Date(expectedAt).toISOString(),
@@ -970,6 +1003,29 @@ function withSubscriptionAccountId(obligation, rows) {
970
1003
  return row;
971
1004
  });
972
1005
  }
1006
+ function assertRowsWithinFrozenPackageCoverage(obligation, rows) {
1007
+ const coveredPackageIds = new Set(obligation.coverage.coveredPackageIds ?? []);
1008
+ const packageBindings = obligation.packageBindings ?? [];
1009
+ if (coveredPackageIds.size === 0 && packageBindings.length === 0) {
1010
+ if (rows.some((row) => row.package_id !== void 0)) {
1011
+ throw new ReportingSourceConfigurationError("Reporting source row is outside frozen package coverage");
1012
+ }
1013
+ return;
1014
+ }
1015
+ const packagesByConstituent = new Map(
1016
+ obligation.constituents.filter((constituent) => constituent.constituentKind === "package_item").map((constituent) => [constituent.constituentId, constituent.packageId])
1017
+ );
1018
+ const coveredPairs = new Set(
1019
+ packageBindings.map(
1020
+ (binding) => JSON.stringify([binding.mediaBuyId, packagesByConstituent.get(binding.constituentId)])
1021
+ )
1022
+ );
1023
+ for (const row of rows) {
1024
+ if (typeof row.media_buy_id !== "string" || typeof row.package_id !== "string" || !coveredPackageIds.has(row.package_id) || !coveredPairs.has(JSON.stringify([row.media_buy_id, row.package_id]))) {
1025
+ throw new ReportingSourceConfigurationError("Reporting source row is outside frozen package coverage");
1026
+ }
1027
+ }
1028
+ }
973
1029
  function boundedId(value, field) {
974
1030
  if (typeof value !== "string" || value.length === 0 || value.length > 255) {
975
1031
  throw new TypeError(`${field} must be a bounded non-empty string`);
@@ -981,6 +1037,9 @@ function sourceRequest(obligation, offering, previous, adjustments, now) {
981
1037
  const periodEnd = instant(obligation.period.end, "period.end");
982
1038
  const cutoff = new Date(Math.min(now.getTime(), periodEnd)).toISOString();
983
1039
  const productIds = [...new Set(obligation.constituents.map((value) => value.productId))].sort();
1040
+ const packageIds = [
1041
+ ...new Set(obligation.constituents.flatMap((value) => value.packageId ? [value.packageId] : []))
1042
+ ].sort();
984
1043
  return {
985
1044
  contractVersion: import_source.REPORTING_SOURCE_CONTRACT_VERSION_V1,
986
1045
  identity: {
@@ -1019,7 +1078,8 @@ function sourceRequest(obligation, offering, previous, adjustments, now) {
1019
1078
  constituents: structuredClone(obligation.constituents),
1020
1079
  productIds,
1021
1080
  mediaBuyIds: [...obligation.mediaBuyIds],
1022
- packageIds: [],
1081
+ packageIds,
1082
+ ...obligation.packageBindings?.length ? { packageBindings: structuredClone(obligation.packageBindings) } : {},
1023
1083
  denominatorFingerprint: (0, import_source.reportingCoverageDenominatorFingerprintV1)(obligation.constituents)
1024
1084
  },
1025
1085
  requestedMetrics: [...obligation.requestedMetrics],
@@ -1270,7 +1330,7 @@ function buildAdjustment(obligation, official, manifestReference, manifest, rows
1270
1330
  name: total.name,
1271
1331
  value: subtractDecimal(total.value, prior.value),
1272
1332
  value_type: total.value_type === "decimal" || prior.value_type === "decimal" ? "decimal" : "integer",
1273
- ...total.unit ? { unit: total.unit } : {}
1333
+ ...prior.unit !== void 0 ? { unit: prior.unit } : {}
1274
1334
  }
1275
1335
  ] : [];
1276
1336
  });
@@ -1329,7 +1389,13 @@ function reportingControlTotals(rows, metrics) {
1329
1389
  if (parsed.scale > 0) valueType = "decimal";
1330
1390
  sum = addDecimal(sum, parsed);
1331
1391
  }
1332
- return [{ name, value: formatDecimal(sum), value_type: valueType }];
1392
+ return [
1393
+ {
1394
+ name,
1395
+ value: formatDecimal(sum),
1396
+ value_type: valueType
1397
+ }
1398
+ ];
1333
1399
  });
1334
1400
  }
1335
1401
  function isCanonicalDecimal(value) {
@@ -1437,10 +1503,10 @@ function wireCoverage(obligation) {
1437
1503
  partially_covered_media_buy_ids: obligation.coverage.partiallyCoveredMediaBuyIds,
1438
1504
  unsupported_media_buy_ids: obligation.coverage.unsupportedMediaBuyIds,
1439
1505
  unknown_media_buy_ids: obligation.coverage.unknownMediaBuyIds,
1440
- package_ids: [],
1441
- covered_package_ids: [],
1442
- unsupported_package_ids: [],
1443
- unknown_package_ids: [],
1506
+ package_ids: obligation.coverage.packageIds ?? [],
1507
+ covered_package_ids: obligation.coverage.coveredPackageIds ?? [],
1508
+ unsupported_package_ids: obligation.coverage.unsupportedPackageIds ?? [],
1509
+ unknown_package_ids: obligation.coverage.unknownPackageIds ?? [],
1444
1510
  limitations: []
1445
1511
  };
1446
1512
  }
@@ -1666,6 +1732,15 @@ function validateConfigurationAgainstOffering(configuration, offering, ownership
1666
1732
  ])) {
1667
1733
  throw new Error("Reporting configuration media-buy scope must equal its constituent denominator");
1668
1734
  }
1735
+ const packageConstituents = configuration.constituents.filter((value) => value.constituentKind === "package_item");
1736
+ const packageConstituentIds = new Set(packageConstituents.map((value) => value.constituentId));
1737
+ const packageBindings = configuration.packageBindings ?? [];
1738
+ const mediaBuyIds = new Set(configuration.mediaBuyIds);
1739
+ if (!Array.isArray(packageBindings) || packageConstituentIds.size !== packageConstituents.length || packageBindings.length !== packageConstituents.length || packageBindings.some(
1740
+ (value) => !value || typeof value.constituentId !== "string" || typeof value.mediaBuyId !== "string" || !packageConstituentIds.has(value.constituentId) || !mediaBuyIds.has(value.mediaBuyId)
1741
+ ) || new Set(packageBindings.map((value) => value.constituentId)).size !== packageBindings.length) {
1742
+ throw new TypeError("Reporting configuration package bindings must match its authorized constituents");
1743
+ }
1669
1744
  }
1670
1745
  function sameMembers(left, right) {
1671
1746
  return (0, import_source.canonicalJsonV1)([...left].sort()) === (0, import_source.canonicalJsonV1)([...right].sort());
@@ -604,6 +604,7 @@ function createReportingProducer(options) {
604
604
  obligation,
605
605
  await readManifestRows(options.source, obligation, manifest, executionSignal, settlementGrace)
606
606
  );
607
+ assertRowsWithinFrozenPackageCoverage(obligation, rows);
607
608
  validateManifestFinalityForObligation(obligation, manifest);
608
609
  if (previous.some((value) => value.finality === "official")) {
609
610
  const official = previous.find((value) => value.finality === "official");
@@ -762,6 +763,7 @@ function planObligation(configuration, periodOrdinal, createdAt) {
762
763
  periodOrdinal,
763
764
  period: { start: new Date(start).toISOString(), end: new Date(end).toISOString() },
764
765
  constituents: configuration.constituents,
766
+ ...configuration.packageBindings?.length ? { packageBindings: configuration.packageBindings } : {},
765
767
  coverageRequirement: "full"
766
768
  };
767
769
  const semanticFingerprint = prefixedDigest(semantic);
@@ -794,12 +796,23 @@ function planObligation(configuration, periodOrdinal, createdAt) {
794
796
  fullyCoveredMediaBuyIds: [...configuration.mediaBuyIds].sort(),
795
797
  partiallyCoveredMediaBuyIds: [],
796
798
  unsupportedMediaBuyIds: [],
797
- unknownMediaBuyIds: []
799
+ unknownMediaBuyIds: [],
800
+ ...configuration.packageBindings?.length ? {
801
+ packageIds: [
802
+ ...new Set(configuration.constituents.flatMap((value) => value.packageId ? [value.packageId] : []))
803
+ ].sort(),
804
+ coveredPackageIds: [
805
+ ...new Set(configuration.constituents.flatMap((value) => value.packageId ? [value.packageId] : []))
806
+ ].sort(),
807
+ unsupportedPackageIds: [],
808
+ unknownPackageIds: []
809
+ } : {}
798
810
  },
799
811
  requestedMetrics: [...configuration.requestedMetrics],
800
812
  requestedDimensions: [...configuration.requestedDimensions],
801
813
  constituents: structuredClone(configuration.constituents),
802
814
  mediaBuyIds: [...configuration.mediaBuyIds].sort(),
815
+ ...configuration.packageBindings?.length ? { packageBindings: structuredClone(configuration.packageBindings) } : {},
803
816
  sourceSettings: structuredClone(configuration.sourceSettings),
804
817
  contract: structuredClone(configuration.contract),
805
818
  expectedAt: new Date(expectedAt).toISOString(),
@@ -823,7 +836,8 @@ function subscriptionConfiguration(input, plan, installedAt) {
823
836
  "historyStartOrdinal",
824
837
  "owedSet",
825
838
  "constituents",
826
- "mediaBuyIds"
839
+ "mediaBuyIds",
840
+ "packageBindings"
827
841
  ]) {
828
842
  if (Object.hasOwn(input, field)) {
829
843
  throw new TypeError(`Subscription configuration input must not supply ${field}`);
@@ -895,6 +909,15 @@ function planOwedSetObligation(configuration, input, offering, owedThroughMs, cr
895
909
  if (!sameMembers(mediaBuyIds, [...new Set(constituents.map((value) => value.mediaBuyId).filter(Boolean))])) {
896
910
  throw new Error("Subscription obligation media buys must equal its constituent denominator");
897
911
  }
912
+ const packageBindings = structuredClone(input.packageBindings ?? []);
913
+ const packageConstituentIds = new Set(
914
+ constituents.filter((value) => value.constituentKind === "package_item").map((value) => value.constituentId)
915
+ );
916
+ if (packageBindings.length !== packageConstituentIds.size || new Set(packageBindings.map((value) => value.constituentId)).size !== packageBindings.length || packageBindings.some(
917
+ (value) => !packageConstituentIds.has(value.constituentId) || !mediaBuyIds.includes(value.mediaBuyId)
918
+ )) {
919
+ throw new TypeError("Subscription obligation package bindings must match its authorized constituents");
920
+ }
898
921
  const listedProducts = listedReportingSourceProductIdsV1(offering.applicability);
899
922
  if (listedProducts !== void 0 && constituents.some((value) => !listedProducts.includes(value.productId))) {
900
923
  throw new Error("Reporting constituent product is outside its offering applicability");
@@ -914,6 +937,7 @@ function planOwedSetObligation(configuration, input, offering, owedThroughMs, cr
914
937
  period: { start: periodStart, end: periodEnd },
915
938
  constituents,
916
939
  mediaBuyIds,
940
+ ...packageBindings.length ? { packageBindings } : {},
917
941
  coverageRequirement: "full"
918
942
  };
919
943
  return {
@@ -942,12 +966,21 @@ function planOwedSetObligation(configuration, input, offering, owedThroughMs, cr
942
966
  fullyCoveredMediaBuyIds: [...mediaBuyIds],
943
967
  partiallyCoveredMediaBuyIds: [],
944
968
  unsupportedMediaBuyIds: [],
945
- unknownMediaBuyIds: []
969
+ unknownMediaBuyIds: [],
970
+ ...packageBindings.length ? {
971
+ packageIds: [...new Set(constituents.flatMap((value) => value.packageId ? [value.packageId] : []))].sort(),
972
+ coveredPackageIds: [
973
+ ...new Set(constituents.flatMap((value) => value.packageId ? [value.packageId] : []))
974
+ ].sort(),
975
+ unsupportedPackageIds: [],
976
+ unknownPackageIds: []
977
+ } : {}
946
978
  },
947
979
  requestedMetrics: [...configuration.requestedMetrics],
948
980
  requestedDimensions: [...configuration.requestedDimensions],
949
981
  constituents,
950
982
  mediaBuyIds,
983
+ ...packageBindings.length ? { packageBindings } : {},
951
984
  sourceSettings: structuredClone(configuration.sourceSettings),
952
985
  contract: structuredClone(configuration.contract),
953
986
  expectedAt: new Date(expectedAt).toISOString(),
@@ -972,6 +1005,29 @@ function withSubscriptionAccountId(obligation, rows) {
972
1005
  return row;
973
1006
  });
974
1007
  }
1008
+ function assertRowsWithinFrozenPackageCoverage(obligation, rows) {
1009
+ const coveredPackageIds = new Set(obligation.coverage.coveredPackageIds ?? []);
1010
+ const packageBindings = obligation.packageBindings ?? [];
1011
+ if (coveredPackageIds.size === 0 && packageBindings.length === 0) {
1012
+ if (rows.some((row) => row.package_id !== void 0)) {
1013
+ throw new ReportingSourceConfigurationError("Reporting source row is outside frozen package coverage");
1014
+ }
1015
+ return;
1016
+ }
1017
+ const packagesByConstituent = new Map(
1018
+ obligation.constituents.filter((constituent) => constituent.constituentKind === "package_item").map((constituent) => [constituent.constituentId, constituent.packageId])
1019
+ );
1020
+ const coveredPairs = new Set(
1021
+ packageBindings.map(
1022
+ (binding) => JSON.stringify([binding.mediaBuyId, packagesByConstituent.get(binding.constituentId)])
1023
+ )
1024
+ );
1025
+ for (const row of rows) {
1026
+ if (typeof row.media_buy_id !== "string" || typeof row.package_id !== "string" || !coveredPackageIds.has(row.package_id) || !coveredPairs.has(JSON.stringify([row.media_buy_id, row.package_id]))) {
1027
+ throw new ReportingSourceConfigurationError("Reporting source row is outside frozen package coverage");
1028
+ }
1029
+ }
1030
+ }
975
1031
  function boundedId(value, field) {
976
1032
  if (typeof value !== "string" || value.length === 0 || value.length > 255) {
977
1033
  throw new TypeError(`${field} must be a bounded non-empty string`);
@@ -983,6 +1039,9 @@ function sourceRequest(obligation, offering, previous, adjustments, now) {
983
1039
  const periodEnd = instant(obligation.period.end, "period.end");
984
1040
  const cutoff = new Date(Math.min(now.getTime(), periodEnd)).toISOString();
985
1041
  const productIds = [...new Set(obligation.constituents.map((value) => value.productId))].sort();
1042
+ const packageIds = [
1043
+ ...new Set(obligation.constituents.flatMap((value) => value.packageId ? [value.packageId] : []))
1044
+ ].sort();
986
1045
  return {
987
1046
  contractVersion: REPORTING_SOURCE_CONTRACT_VERSION_V1,
988
1047
  identity: {
@@ -1021,7 +1080,8 @@ function sourceRequest(obligation, offering, previous, adjustments, now) {
1021
1080
  constituents: structuredClone(obligation.constituents),
1022
1081
  productIds,
1023
1082
  mediaBuyIds: [...obligation.mediaBuyIds],
1024
- packageIds: [],
1083
+ packageIds,
1084
+ ...obligation.packageBindings?.length ? { packageBindings: structuredClone(obligation.packageBindings) } : {},
1025
1085
  denominatorFingerprint: reportingCoverageDenominatorFingerprintV1(obligation.constituents)
1026
1086
  },
1027
1087
  requestedMetrics: [...obligation.requestedMetrics],
@@ -1272,7 +1332,7 @@ function buildAdjustment(obligation, official, manifestReference, manifest, rows
1272
1332
  name: total.name,
1273
1333
  value: subtractDecimal(total.value, prior.value),
1274
1334
  value_type: total.value_type === "decimal" || prior.value_type === "decimal" ? "decimal" : "integer",
1275
- ...total.unit ? { unit: total.unit } : {}
1335
+ ...prior.unit !== void 0 ? { unit: prior.unit } : {}
1276
1336
  }
1277
1337
  ] : [];
1278
1338
  });
@@ -1331,7 +1391,13 @@ function reportingControlTotals(rows, metrics) {
1331
1391
  if (parsed.scale > 0) valueType = "decimal";
1332
1392
  sum = addDecimal(sum, parsed);
1333
1393
  }
1334
- return [{ name, value: formatDecimal(sum), value_type: valueType }];
1394
+ return [
1395
+ {
1396
+ name,
1397
+ value: formatDecimal(sum),
1398
+ value_type: valueType
1399
+ }
1400
+ ];
1335
1401
  });
1336
1402
  }
1337
1403
  function isCanonicalDecimal(value) {
@@ -1439,10 +1505,10 @@ function wireCoverage(obligation) {
1439
1505
  partially_covered_media_buy_ids: obligation.coverage.partiallyCoveredMediaBuyIds,
1440
1506
  unsupported_media_buy_ids: obligation.coverage.unsupportedMediaBuyIds,
1441
1507
  unknown_media_buy_ids: obligation.coverage.unknownMediaBuyIds,
1442
- package_ids: [],
1443
- covered_package_ids: [],
1444
- unsupported_package_ids: [],
1445
- unknown_package_ids: [],
1508
+ package_ids: obligation.coverage.packageIds ?? [],
1509
+ covered_package_ids: obligation.coverage.coveredPackageIds ?? [],
1510
+ unsupported_package_ids: obligation.coverage.unsupportedPackageIds ?? [],
1511
+ unknown_package_ids: obligation.coverage.unknownPackageIds ?? [],
1446
1512
  limitations: []
1447
1513
  };
1448
1514
  }
@@ -1668,6 +1734,15 @@ function validateConfigurationAgainstOffering(configuration, offering, ownership
1668
1734
  ])) {
1669
1735
  throw new Error("Reporting configuration media-buy scope must equal its constituent denominator");
1670
1736
  }
1737
+ const packageConstituents = configuration.constituents.filter((value) => value.constituentKind === "package_item");
1738
+ const packageConstituentIds = new Set(packageConstituents.map((value) => value.constituentId));
1739
+ const packageBindings = configuration.packageBindings ?? [];
1740
+ const mediaBuyIds = new Set(configuration.mediaBuyIds);
1741
+ if (!Array.isArray(packageBindings) || packageConstituentIds.size !== packageConstituents.length || packageBindings.length !== packageConstituents.length || packageBindings.some(
1742
+ (value) => !value || typeof value.constituentId !== "string" || typeof value.mediaBuyId !== "string" || !packageConstituentIds.has(value.constituentId) || !mediaBuyIds.has(value.mediaBuyId)
1743
+ ) || new Set(packageBindings.map((value) => value.constituentId)).size !== packageBindings.length) {
1744
+ throw new TypeError("Reporting configuration package bindings must match its authorized constituents");
1745
+ }
1671
1746
  }
1672
1747
  function sameMembers(left, right) {
1673
1748
  return canonicalJsonV1([...left].sort()) === canonicalJsonV1([...right].sort());
@@ -22,6 +22,10 @@ export type ReportingObservedFinalityV1 = 'none' | ReportingFinalityV1;
22
22
  export type ReportingLedgerAccountV1 = Readonly<{
23
23
  account_id: string;
24
24
  }>;
25
+ export interface ReportingPackageBindingV1 {
26
+ constituentId: string;
27
+ mediaBuyId: string;
28
+ }
25
29
  export interface ReportingLedgerCoverageV1 {
26
30
  status: 'full' | 'partial' | 'none' | 'unknown';
27
31
  evaluatedAt: string;
@@ -30,6 +34,10 @@ export interface ReportingLedgerCoverageV1 {
30
34
  partiallyCoveredMediaBuyIds: string[];
31
35
  unsupportedMediaBuyIds: string[];
32
36
  unknownMediaBuyIds: string[];
37
+ packageIds?: string[];
38
+ coveredPackageIds?: string[];
39
+ unsupportedPackageIds?: string[];
40
+ unknownPackageIds?: string[];
33
41
  }
34
42
  /** Runtime timezone rules frozen into a source-calendar configuration generation. */
35
43
  export interface ReportingCalendarRulesV1 {
@@ -86,6 +94,7 @@ export interface ReportingLedgerConfigurationV1 {
86
94
  requestedDimensions: string[];
87
95
  constituents: ReportingSourceSliceRequestV1['coverage']['constituents'];
88
96
  mediaBuyIds: string[];
97
+ packageBindings?: ReportingPackageBindingV1[];
89
98
  sourceTimezone: string;
90
99
  /**
91
100
  * Host rule-set identity used to resolve calendar boundaries. Calendar
@@ -253,6 +262,7 @@ export interface ReportingLedgerObligationV1 {
253
262
  requestedDimensions: string[];
254
263
  constituents: ReportingSourceSliceRequestV1['coverage']['constituents'];
255
264
  mediaBuyIds: string[];
265
+ packageBindings?: ReportingPackageBindingV1[];
256
266
  sourceSettings: ReportingSourceSliceRequestV1['sourceSettings'];
257
267
  contract: ReportingSourceSliceRequestV1['contract'];
258
268
  expectedAt: string;
@@ -1262,7 +1272,7 @@ export interface ReportingProducerContactV1 {
1262
1272
  *
1263
1273
  * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
1264
1274
  */
1265
- export type ReportingSubscriptionConfigurationInputV1 = Omit<ReportingLedgerConfigurationV1, 'configurationId' | 'installedAt' | 'semanticFingerprint' | 'calendarRules' | 'historyStart' | 'historyStartOrdinal' | 'owedSet' | 'constituents' | 'mediaBuyIds' | 'subscription'> & {
1275
+ export type ReportingSubscriptionConfigurationInputV1 = Omit<ReportingLedgerConfigurationV1, 'configurationId' | 'installedAt' | 'semanticFingerprint' | 'calendarRules' | 'historyStart' | 'historyStartOrdinal' | 'owedSet' | 'constituents' | 'mediaBuyIds' | 'packageBindings' | 'subscription'> & {
1266
1276
  subscription: ReportingLedgerSubscriptionV1;
1267
1277
  };
1268
1278
  /**
@@ -1281,6 +1291,7 @@ export interface ReportingSubscriptionLedgerObligationInputV1 {
1281
1291
  /** Frozen at the period end (`scope_resolved_at`). Must equal the constituents' media buys. */
1282
1292
  mediaBuyIds: string[];
1283
1293
  constituents: ReportingSourceSliceRequestV1['coverage']['constituents'];
1294
+ packageBindings?: ReportingPackageBindingV1[];
1284
1295
  /** A billing cutover stub (adcp#8617): `period` is [E, first incoming boundary). */
1285
1296
  stub?: true;
1286
1297
  }
@@ -22,6 +22,10 @@ export type ReportingObservedFinalityV1 = 'none' | ReportingFinalityV1;
22
22
  export type ReportingLedgerAccountV1 = Readonly<{
23
23
  account_id: string;
24
24
  }>;
25
+ export interface ReportingPackageBindingV1 {
26
+ constituentId: string;
27
+ mediaBuyId: string;
28
+ }
25
29
  export interface ReportingLedgerCoverageV1 {
26
30
  status: 'full' | 'partial' | 'none' | 'unknown';
27
31
  evaluatedAt: string;
@@ -30,6 +34,10 @@ export interface ReportingLedgerCoverageV1 {
30
34
  partiallyCoveredMediaBuyIds: string[];
31
35
  unsupportedMediaBuyIds: string[];
32
36
  unknownMediaBuyIds: string[];
37
+ packageIds?: string[];
38
+ coveredPackageIds?: string[];
39
+ unsupportedPackageIds?: string[];
40
+ unknownPackageIds?: string[];
33
41
  }
34
42
  /** Runtime timezone rules frozen into a source-calendar configuration generation. */
35
43
  export interface ReportingCalendarRulesV1 {
@@ -86,6 +94,7 @@ export interface ReportingLedgerConfigurationV1 {
86
94
  requestedDimensions: string[];
87
95
  constituents: ReportingSourceSliceRequestV1['coverage']['constituents'];
88
96
  mediaBuyIds: string[];
97
+ packageBindings?: ReportingPackageBindingV1[];
89
98
  sourceTimezone: string;
90
99
  /**
91
100
  * Host rule-set identity used to resolve calendar boundaries. Calendar
@@ -253,6 +262,7 @@ export interface ReportingLedgerObligationV1 {
253
262
  requestedDimensions: string[];
254
263
  constituents: ReportingSourceSliceRequestV1['coverage']['constituents'];
255
264
  mediaBuyIds: string[];
265
+ packageBindings?: ReportingPackageBindingV1[];
256
266
  sourceSettings: ReportingSourceSliceRequestV1['sourceSettings'];
257
267
  contract: ReportingSourceSliceRequestV1['contract'];
258
268
  expectedAt: string;
@@ -1262,7 +1272,7 @@ export interface ReportingProducerContactV1 {
1262
1272
  *
1263
1273
  * @experimental Reliable Reporting storage surface: breaking changes may ship in minor releases. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/REPORTING-STABILITY.md
1264
1274
  */
1265
- export type ReportingSubscriptionConfigurationInputV1 = Omit<ReportingLedgerConfigurationV1, 'configurationId' | 'installedAt' | 'semanticFingerprint' | 'calendarRules' | 'historyStart' | 'historyStartOrdinal' | 'owedSet' | 'constituents' | 'mediaBuyIds' | 'subscription'> & {
1275
+ export type ReportingSubscriptionConfigurationInputV1 = Omit<ReportingLedgerConfigurationV1, 'configurationId' | 'installedAt' | 'semanticFingerprint' | 'calendarRules' | 'historyStart' | 'historyStartOrdinal' | 'owedSet' | 'constituents' | 'mediaBuyIds' | 'packageBindings' | 'subscription'> & {
1266
1276
  subscription: ReportingLedgerSubscriptionV1;
1267
1277
  };
1268
1278
  /**
@@ -1281,6 +1291,7 @@ export interface ReportingSubscriptionLedgerObligationInputV1 {
1281
1291
  /** Frozen at the period end (`scope_resolved_at`). Must equal the constituents' media buys. */
1282
1292
  mediaBuyIds: string[];
1283
1293
  constituents: ReportingSourceSliceRequestV1['coverage']['constituents'];
1294
+ packageBindings?: ReportingPackageBindingV1[];
1284
1295
  /** A billing cutover stub (adcp#8617): `period` is [E, first incoming boundary). */
1285
1296
  stub?: true;
1286
1297
  }
@@ -57,6 +57,7 @@ export interface ReliableReportingAdapterV1 {
57
57
  */
58
58
  export interface ReliableReportingCoverageV1 {
59
59
  constituents: ReportingLedgerConfigurationV1['constituents'];
60
+ packageBindings?: ReportingLedgerConfigurationV1['packageBindings'];
60
61
  }
61
62
  export interface ReliableReportingSourceRouteV1 {
62
63
  /** Key in `adapters`; selected by trusted host code, never by buyer input. */
@@ -66,7 +67,7 @@ export interface ReliableReportingSourceRouteV1 {
66
67
  /** Trusted upstream reporting clock for this account/scope. */
67
68
  sourceTimezone: string;
68
69
  }
69
- type LedgerInstallInput = Omit<ReportingLedgerConfigurationV1, 'configurationId' | 'installedAt' | 'semanticFingerprint' | 'calendarRules' | 'historyStart' | 'historyStartOrdinal' | 'subscription' | 'owedSet' | 'account' | 'sourceScope' | 'sourceTimezone' | 'sourceSettings' | 'contract' | 'constituents' | 'mediaBuyIds'>;
70
+ type LedgerInstallInput = Omit<ReportingLedgerConfigurationV1, 'configurationId' | 'installedAt' | 'semanticFingerprint' | 'calendarRules' | 'historyStart' | 'historyStartOrdinal' | 'subscription' | 'owedSet' | 'account' | 'sourceScope' | 'sourceTimezone' | 'sourceSettings' | 'contract' | 'constituents' | 'mediaBuyIds' | 'packageBindings'>;
70
71
  /**
71
72
  * Seller-resolved configuration facts. `currency`, account identity, source
72
73
  * scope, timezone, and source contract are deliberately absent.