@adcp/sdk 17.0.0-beta.21 → 17.0.0-beta.23

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 (223) hide show
  1. package/README.md +26 -2
  2. package/dist/lib/adapters/version/index.d.mts +1 -1
  3. package/dist/lib/adapters/version/index.d.ts +1 -1
  4. package/dist/lib/adapters/version/index.js +2 -0
  5. package/dist/lib/adapters/version/index.mjs +2 -0
  6. package/dist/lib/adapters/version/negotiate.d.mts +13 -0
  7. package/dist/lib/adapters/version/negotiate.d.ts +13 -0
  8. package/dist/lib/adapters/version/negotiate.js +6 -0
  9. package/dist/lib/adapters/version/negotiate.mjs +5 -0
  10. package/dist/lib/client/core.d.mts +4 -0
  11. package/dist/lib/client/core.d.ts +4 -0
  12. package/dist/lib/client/core.js +13 -0
  13. package/dist/lib/client/core.mjs +12 -0
  14. package/dist/lib/conformance/property-lists.d.mts +1 -1
  15. package/dist/lib/conformance/property-lists.d.ts +1 -1
  16. package/dist/lib/conformance/property-lists.js +1 -1
  17. package/dist/lib/conformance/property-lists.mjs +1 -1
  18. package/dist/lib/core/SingleAgentClient.d.mts +23 -1
  19. package/dist/lib/core/SingleAgentClient.d.ts +23 -1
  20. package/dist/lib/core/SingleAgentClient.js +102 -18
  21. package/dist/lib/core/SingleAgentClient.mjs +108 -18
  22. package/dist/lib/core/targeting-helpers.d.mts +123 -0
  23. package/dist/lib/core/targeting-helpers.d.ts +123 -0
  24. package/dist/lib/core/targeting-helpers.js +412 -0
  25. package/dist/lib/core/targeting-helpers.mjs +370 -0
  26. package/dist/lib/entrypoints/client-account-changes.d.mts +5 -0
  27. package/dist/lib/entrypoints/client-account-changes.d.ts +5 -0
  28. package/dist/lib/entrypoints/client-account-changes.js +28 -0
  29. package/dist/lib/entrypoints/client-account-changes.mjs +4 -0
  30. package/dist/lib/entrypoints/client-webhook-stores.d.mts +2 -0
  31. package/dist/lib/entrypoints/client-webhook-stores.d.ts +2 -0
  32. package/dist/lib/entrypoints/client-webhook-stores.js +37 -0
  33. package/dist/lib/entrypoints/client-webhook-stores.mjs +16 -0
  34. package/dist/lib/entrypoints/discovery.d.mts +9 -0
  35. package/dist/lib/entrypoints/discovery.d.ts +9 -0
  36. package/dist/lib/entrypoints/discovery.js +72 -0
  37. package/dist/lib/entrypoints/discovery.mjs +56 -0
  38. package/dist/lib/entrypoints/errors.d.mts +11 -0
  39. package/dist/lib/entrypoints/errors.d.ts +11 -0
  40. package/dist/lib/entrypoints/errors.js +159 -0
  41. package/dist/lib/entrypoints/errors.mjs +132 -0
  42. package/dist/lib/entrypoints/media-buy.d.mts +5 -0
  43. package/dist/lib/entrypoints/media-buy.d.ts +5 -0
  44. package/dist/lib/entrypoints/media-buy.js +119 -0
  45. package/dist/lib/entrypoints/media-buy.mjs +100 -0
  46. package/dist/lib/entrypoints/registry.d.mts +5 -0
  47. package/dist/lib/entrypoints/registry.d.ts +5 -0
  48. package/dist/lib/entrypoints/registry.js +61 -0
  49. package/dist/lib/entrypoints/registry.mjs +40 -0
  50. package/dist/lib/entrypoints/utils.d.mts +7 -0
  51. package/dist/lib/entrypoints/utils.d.ts +7 -0
  52. package/dist/lib/entrypoints/utils.js +100 -0
  53. package/dist/lib/entrypoints/utils.mjs +72 -0
  54. package/dist/lib/entrypoints/version.d.mts +3 -0
  55. package/dist/lib/entrypoints/version.d.ts +3 -0
  56. package/dist/lib/entrypoints/version.js +57 -0
  57. package/dist/lib/entrypoints/version.mjs +36 -0
  58. package/dist/lib/index.d.mts +1 -1
  59. package/dist/lib/index.d.ts +1 -1
  60. package/dist/lib/media-buy/action-contracts.js +3 -3
  61. package/dist/lib/media-buy/action-contracts.mjs +1 -1
  62. package/dist/lib/media-buy/creative-start-policy.d.mts +19 -0
  63. package/dist/lib/media-buy/creative-start-policy.d.ts +19 -0
  64. package/dist/lib/media-buy/creative-start-policy.js +59 -0
  65. package/dist/lib/media-buy/creative-start-policy.mjs +31 -0
  66. package/dist/lib/media-buy/valid-actions.d.mts +47 -0
  67. package/dist/lib/media-buy/valid-actions.d.ts +47 -0
  68. package/dist/lib/media-buy/valid-actions.js +42 -0
  69. package/dist/lib/media-buy/valid-actions.mjs +18 -0
  70. package/dist/lib/net/pin-and-bind-fetch.d.mts +121 -0
  71. package/dist/lib/net/pin-and-bind-fetch.d.ts +121 -0
  72. package/dist/lib/net/pin-and-bind-fetch.js +209 -0
  73. package/dist/lib/net/pin-and-bind-fetch.mjs +183 -0
  74. package/dist/lib/protocols/mcp-modern.js +20 -4
  75. package/dist/lib/protocols/mcp-modern.mjs +20 -4
  76. package/dist/lib/registry/types.generated.d.ts +224 -3
  77. package/dist/lib/reporting/ledger/index.d.mts +1 -0
  78. package/dist/lib/reporting/ledger/index.d.ts +1 -0
  79. package/dist/lib/reporting/ledger/index.js +3 -1
  80. package/dist/lib/reporting/ledger/index.mjs +1 -0
  81. package/dist/lib/reporting/ledger/instant.d.mts +5 -0
  82. package/dist/lib/reporting/ledger/instant.d.ts +5 -0
  83. package/dist/lib/reporting/ledger/instant.js +10 -0
  84. package/dist/lib/reporting/ledger/instant.mjs +9 -0
  85. package/dist/lib/reporting/ledger/issue-events.d.mts +333 -0
  86. package/dist/lib/reporting/ledger/issue-events.d.ts +333 -0
  87. package/dist/lib/reporting/ledger/issue-events.js +310 -0
  88. package/dist/lib/reporting/ledger/issue-events.mjs +282 -0
  89. package/dist/lib/reporting/service/index.d.mts +36 -1
  90. package/dist/lib/reporting/service/index.d.ts +36 -1
  91. package/dist/lib/reporting/service/index.js +51 -1
  92. package/dist/lib/reporting/service/index.mjs +52 -2
  93. package/dist/lib/reporting/service/scheduler-support.d.mts +1 -1
  94. package/dist/lib/reporting/service/scheduler-support.d.ts +1 -1
  95. package/dist/lib/reporting/service/scheduler-support.js +1 -1
  96. package/dist/lib/reporting/service/scheduler-support.mjs +1 -1
  97. package/dist/lib/server/capabilities-release-projection.d.mts +43 -0
  98. package/dist/lib/server/capabilities-release-projection.d.ts +43 -0
  99. package/dist/lib/server/capabilities-release-projection.js +128 -0
  100. package/dist/lib/server/capabilities-release-projection.mjs +112 -0
  101. package/dist/lib/server/create-adcp-server.d.mts +29 -5
  102. package/dist/lib/server/create-adcp-server.d.ts +29 -5
  103. package/dist/lib/server/create-adcp-server.js +97 -24
  104. package/dist/lib/server/create-adcp-server.mjs +108 -23
  105. package/dist/lib/server/decisioning/capabilities.d.mts +27 -0
  106. package/dist/lib/server/decisioning/capabilities.d.ts +27 -0
  107. package/dist/lib/server/decisioning/runtime/from-platform.js +99 -27
  108. package/dist/lib/server/decisioning/runtime/from-platform.mjs +103 -27
  109. package/dist/lib/server/declared-input-schema.d.mts +108 -0
  110. package/dist/lib/server/declared-input-schema.d.ts +108 -0
  111. package/dist/lib/server/declared-input-schema.js +167 -0
  112. package/dist/lib/server/declared-input-schema.mjs +137 -0
  113. package/dist/lib/server/envelope-allowlist.d.mts +1 -105
  114. package/dist/lib/server/envelope-allowlist.d.ts +1 -105
  115. package/dist/lib/server/envelope-allowlist.js +3 -79
  116. package/dist/lib/server/envelope-allowlist.mjs +1 -71
  117. package/dist/lib/server/errors.d.mts +1 -186
  118. package/dist/lib/server/errors.d.ts +1 -186
  119. package/dist/lib/server/errors.js +3 -98
  120. package/dist/lib/server/errors.mjs +1 -94
  121. package/dist/lib/server/index.d.mts +1 -1
  122. package/dist/lib/server/index.d.ts +1 -1
  123. package/dist/lib/server/mcp-modern-server.js +21 -4
  124. package/dist/lib/server/mcp-modern-server.mjs +21 -4
  125. package/dist/lib/server/media-buy-action-resolver.d.mts +7 -0
  126. package/dist/lib/server/media-buy-action-resolver.d.ts +7 -0
  127. package/dist/lib/server/media-buy-action-resolver.js +10 -1
  128. package/dist/lib/server/media-buy-action-resolver.mjs +10 -1
  129. package/dist/lib/server/media-buy-helpers.d.mts +1 -47
  130. package/dist/lib/server/media-buy-helpers.d.ts +1 -47
  131. package/dist/lib/server/media-buy-helpers.js +3 -23
  132. package/dist/lib/server/media-buy-helpers.mjs +1 -18
  133. package/dist/lib/server/pick-safe-details.d.mts +1 -89
  134. package/dist/lib/server/pick-safe-details.d.ts +1 -89
  135. package/dist/lib/server/pick-safe-details.js +3 -61
  136. package/dist/lib/server/pick-safe-details.mjs +1 -56
  137. package/dist/lib/server/pin-and-bind-fetch.d.mts +1 -121
  138. package/dist/lib/server/pin-and-bind-fetch.d.ts +1 -121
  139. package/dist/lib/server/pin-and-bind-fetch.js +3 -190
  140. package/dist/lib/server/pin-and-bind-fetch.mjs +1 -183
  141. package/dist/lib/server/targeting-helpers.d.mts +1 -123
  142. package/dist/lib/server/targeting-helpers.d.ts +1 -123
  143. package/dist/lib/server/targeting-helpers.js +3 -393
  144. package/dist/lib/server/targeting-helpers.mjs +1 -370
  145. package/dist/lib/server/test-controller.js +7 -3
  146. package/dist/lib/server/test-controller.mjs +7 -3
  147. package/dist/lib/storage/memory-ledger.js +219 -1
  148. package/dist/lib/storage/memory-ledger.mjs +223 -1
  149. package/dist/lib/testing/client.js +26 -5
  150. package/dist/lib/testing/client.mjs +24 -5
  151. package/dist/lib/testing/compliance/storyboard-tracks.js +0 -4
  152. package/dist/lib/testing/compliance/storyboard-tracks.mjs +0 -4
  153. package/dist/lib/testing/comply-controller.js +7 -2
  154. package/dist/lib/testing/comply-controller.mjs +7 -2
  155. package/dist/lib/testing/storyboard/request-signing/grader.d.mts +21 -0
  156. package/dist/lib/testing/storyboard/request-signing/grader.d.ts +21 -0
  157. package/dist/lib/testing/storyboard/request-signing/grader.js +31 -0
  158. package/dist/lib/testing/storyboard/request-signing/grader.mjs +30 -0
  159. package/dist/lib/testing/storyboard/request-signing/probe-dispatch.js +1 -1
  160. package/dist/lib/testing/storyboard/request-signing/probe-dispatch.mjs +2 -1
  161. package/dist/lib/testing/storyboard/request-signing/types.d.mts +12 -0
  162. package/dist/lib/testing/storyboard/request-signing/types.d.ts +12 -0
  163. package/dist/lib/testing/storyboard/request-signing/vector-loader.js +7 -2
  164. package/dist/lib/testing/storyboard/request-signing/vector-loader.mjs +7 -2
  165. package/dist/lib/testing/storyboard/runner.js +4 -4
  166. package/dist/lib/testing/storyboard/runner.mjs +4 -4
  167. package/dist/lib/testing/storyboard/task-map.js +4 -1
  168. package/dist/lib/testing/storyboard/task-map.mjs +4 -1
  169. package/dist/lib/testing/storyboard/validations.d.mts +1 -1
  170. package/dist/lib/testing/storyboard/validations.d.ts +1 -1
  171. package/dist/lib/utils/adcp-error-response.d.mts +196 -0
  172. package/dist/lib/utils/adcp-error-response.d.ts +196 -0
  173. package/dist/lib/utils/adcp-error-response.js +118 -0
  174. package/dist/lib/utils/adcp-error-response.mjs +95 -0
  175. package/dist/lib/utils/buyer-retry-policy.js +2 -2
  176. package/dist/lib/utils/buyer-retry-policy.mjs +1 -1
  177. package/dist/lib/utils/capabilities.d.mts +6 -0
  178. package/dist/lib/utils/capabilities.d.ts +6 -0
  179. package/dist/lib/utils/capabilities.js +6 -2
  180. package/dist/lib/utils/capabilities.mjs +6 -2
  181. package/dist/lib/utils/envelope-allowlist.d.mts +105 -0
  182. package/dist/lib/utils/envelope-allowlist.d.ts +105 -0
  183. package/dist/lib/utils/envelope-allowlist.js +98 -0
  184. package/dist/lib/utils/envelope-allowlist.mjs +71 -0
  185. package/dist/lib/utils/pick-safe-details.d.mts +89 -0
  186. package/dist/lib/utils/pick-safe-details.d.ts +89 -0
  187. package/dist/lib/utils/pick-safe-details.js +80 -0
  188. package/dist/lib/utils/pick-safe-details.mjs +56 -0
  189. package/dist/lib/v2/projection/augment-response.d.mts +4 -0
  190. package/dist/lib/v2/projection/augment-response.d.ts +4 -0
  191. package/dist/lib/v2/projection/creative-delivery.d.mts +20 -3
  192. package/dist/lib/v2/projection/creative-delivery.d.ts +20 -3
  193. package/dist/lib/v2/projection/creative-delivery.js +20 -4
  194. package/dist/lib/v2/projection/creative-delivery.mjs +19 -4
  195. package/dist/lib/v2/projection/index.d.mts +2 -2
  196. package/dist/lib/v2/projection/index.d.ts +2 -2
  197. package/dist/lib/v2/projection/index.js +4 -0
  198. package/dist/lib/v2/projection/index.mjs +5 -1
  199. package/dist/lib/v2/projection/legacy-metadata.d.mts +7 -0
  200. package/dist/lib/v2/projection/legacy-metadata.d.ts +7 -0
  201. package/dist/lib/v2/projection/legacy-metadata.js +14 -0
  202. package/dist/lib/v2/projection/legacy-metadata.mjs +12 -0
  203. package/dist/lib/v2/projection/legacy-routes.d.mts +11 -0
  204. package/dist/lib/v2/projection/legacy-routes.d.ts +11 -0
  205. package/dist/lib/v2/projection/legacy-routes.js +2 -1
  206. package/dist/lib/v2/projection/legacy-routes.mjs +7 -2
  207. package/dist/lib/v2/projection/v1-to-v2.d.mts +21 -1
  208. package/dist/lib/v2/projection/v1-to-v2.d.ts +21 -1
  209. package/dist/lib/v2/projection/v1-to-v2.js +18 -11
  210. package/dist/lib/v2/projection/v1-to-v2.mjs +19 -11
  211. package/dist/lib/version.d.mts +3 -3
  212. package/dist/lib/version.d.ts +3 -3
  213. package/dist/lib/version.js +3 -3
  214. package/dist/lib/version.mjs +3 -3
  215. package/docs/TYPE-SUMMARY.md +2 -2
  216. package/docs/guides/CREATIVE-DELIVERY.md +12 -0
  217. package/docs/guides/REPORTING-LEDGER.md +121 -0
  218. package/docs/guides/VALIDATE-YOUR-AGENT.md +1 -0
  219. package/docs/llms.txt +2 -2
  220. package/docs/migration-14.x-rc-worksheet.md +4 -4
  221. package/docs/migration-16-to-17.md +149 -0
  222. package/docs/migration-reporting-storage-package.md +10 -0
  223. package/package.json +106 -1
@@ -0,0 +1,123 @@
1
+ /**
2
+ * Inventory list targeting helpers for AdCP sellers.
3
+ *
4
+ * AdCP 3.0 carries property and collection targeting as references to
5
+ * externally-managed lists (`PropertyListReference`, `CollectionListReference`).
6
+ * The seller resolves those references at serve time and filters its own
7
+ * inventory against the resolved contents.
8
+ *
9
+ * These helpers let a seller handler do that in one line:
10
+ *
11
+ * @example
12
+ * ```typescript
13
+ * import { resolvePropertyList, matchesPropertyList } from '@adcp/sdk/server';
14
+ *
15
+ * if (targeting.property_list) {
16
+ * const list = await resolvePropertyList(targeting.property_list);
17
+ * inventory = inventory.filter(p => matchesPropertyList(p.identifier, list));
18
+ * }
19
+ * ```
20
+ *
21
+ * Resolution goes through MCP (`get_property_list` / `get_collection_list`) on
22
+ * the referenced agent — the same contract a buyer agent uses to fetch the list.
23
+ * Matching follows the identifier and distribution-id semantics defined by the
24
+ * AdCP property and collection specs.
25
+ */
26
+ import type { PropertyListReference, CollectionListReference, GetCollectionListResponse, Identifier } from '../types/tools.generated';
27
+ export interface ResolvedPropertyList {
28
+ listId: string;
29
+ agentUrl: string;
30
+ identifiers: Identifier[];
31
+ cacheValidUntil?: string;
32
+ }
33
+ /** A collection entry as returned by get_collection_list. */
34
+ export type ResolvedCollection = NonNullable<GetCollectionListResponse['collections']>[number];
35
+ export interface ResolvedCollectionList {
36
+ listId: string;
37
+ agentUrl: string;
38
+ collections: ResolvedCollection[];
39
+ cacheValidUntil?: string;
40
+ }
41
+ export type ResolvedListKind = 'property' | 'collection';
42
+ export type ResolvedListCacheValue = ResolvedPropertyList | ResolvedCollectionList;
43
+ export declare const DEFAULT_RESOLVE_LIST_PAGE_SIZE = 1000;
44
+ export interface ResolvedListCacheEntry<TValue extends ResolvedListCacheValue = ResolvedListCacheValue> {
45
+ value: TValue;
46
+ expiresAtMs: number;
47
+ }
48
+ export interface ResolvedListCache {
49
+ get<TValue extends ResolvedListCacheValue>(key: string, nowMs?: number): TValue | undefined;
50
+ set<TValue extends ResolvedListCacheValue>(key: string, entry: ResolvedListCacheEntry<TValue>): void;
51
+ delete(key: string): boolean;
52
+ clear(): void;
53
+ }
54
+ export declare function createResolvedListCache(): ResolvedListCache;
55
+ export declare const defaultResolvedListCache: ResolvedListCache;
56
+ export declare function clearDefaultResolvedListCache(): void;
57
+ export type ResolveListCallTool = (agentUrl: string, toolName: 'get_property_list' | 'get_collection_list', args: Record<string, unknown>, authToken?: string) => Promise<unknown>;
58
+ export interface ResolveListOptions {
59
+ /** Require schema-valid list pages with resolved items. Used for certification. */
60
+ strictResponseValidation?: boolean;
61
+ /** Maximum page size when calling get_property_list / get_collection_list. Defaults to 1000. */
62
+ pageSize?: number;
63
+ /** Maximum number of pages to walk before treating pagination as unsafe. Defaults to 100. */
64
+ maxPages?: number;
65
+ /** Cache for resolved list contents. Defaults to the process-local SDK cache. Pass false to disable caching. */
66
+ cache?: ResolvedListCache | false;
67
+ /**
68
+ * Tenant/principal/auth-context fingerprint for cache scoping when the list
69
+ * reference does not carry an auth_token. Shared caching is disabled without
70
+ * either auth_token or this explicit scope.
71
+ */
72
+ cacheScopeKey?: string;
73
+ /** Clock hook for testing cache expiry. */
74
+ now?: () => Date | number;
75
+ /** MCP call hook for testing/custom transports. */
76
+ callTool?: ResolveListCallTool;
77
+ }
78
+ /**
79
+ * Resolve a PropertyListReference to the concrete identifiers it contains.
80
+ *
81
+ * Calls `get_property_list` on the referenced agent with `resolve: true`.
82
+ * Honors `auth_token` on the reference if present.
83
+ */
84
+ export declare function resolvePropertyList(ref: PropertyListReference, options?: ResolveListOptions): Promise<ResolvedPropertyList>;
85
+ /**
86
+ * Resolve a CollectionListReference to the concrete collections it contains.
87
+ *
88
+ * Calls `get_collection_list` on the referenced agent with `resolve: true`.
89
+ * Honors `auth_token` on the reference if present.
90
+ */
91
+ export declare function resolveCollectionList(ref: CollectionListReference, options?: ResolveListOptions): Promise<ResolvedCollectionList>;
92
+ export declare function resolvedListCacheKey(kind: ResolvedListKind, ref: Pick<PropertyListReference | CollectionListReference, 'agent_url' | 'list_id' | 'auth_token'>, options?: Pick<ResolveListOptions, 'pageSize' | 'cacheScopeKey'>): string | undefined;
93
+ /**
94
+ * Return true if `property` matches any identifier in the resolved list.
95
+ *
96
+ * Domain matching rules (from the AdCP property spec):
97
+ * - Exact match on the identifier value is always accepted.
98
+ * - A `domain` entry of `example.com` also matches `www.example.com` and
99
+ * `m.example.com` — the two canonical aliases for a base domain.
100
+ * - A `domain` entry of `*.example.com` matches every subdomain but NOT the
101
+ * base domain itself.
102
+ * - Non-domain identifier types (ios_bundle, network_id, etc.) use exact
103
+ * string match on both `type` and `value`.
104
+ */
105
+ export declare function matchesPropertyList(property: Identifier, list: ResolvedPropertyList): boolean;
106
+ /**
107
+ * Return true if `collection` matches any entry in the resolved list.
108
+ *
109
+ * Matching modes:
110
+ * - Collections match when `collection_rid` is set on both sides and equal.
111
+ * - Otherwise, they match when they share at least one `distribution_ids`
112
+ * entry with the same `type` and `value`.
113
+ *
114
+ * A collection with no collection_rid and no distribution_ids cannot match —
115
+ * the seller has nothing to match against.
116
+ */
117
+ export declare function matchesCollectionList(collection: {
118
+ collection_rid?: string;
119
+ distribution_ids?: {
120
+ type: string;
121
+ value: string;
122
+ }[];
123
+ }, list: ResolvedCollectionList): boolean;
@@ -0,0 +1,412 @@
1
+ "use strict";
2
+ var __create = Object.create;
3
+ var __defProp = Object.defineProperty;
4
+ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
5
+ var __getOwnPropNames = Object.getOwnPropertyNames;
6
+ var __getProtoOf = Object.getPrototypeOf;
7
+ var __hasOwnProp = Object.prototype.hasOwnProperty;
8
+ var __export = (target, all) => {
9
+ for (var name in all)
10
+ __defProp(target, name, { get: all[name], enumerable: true });
11
+ };
12
+ var __copyProps = (to, from, except, desc) => {
13
+ if (from && typeof from === "object" || typeof from === "function") {
14
+ for (let key of __getOwnPropNames(from))
15
+ if (!__hasOwnProp.call(to, key) && key !== except)
16
+ __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
17
+ }
18
+ return to;
19
+ };
20
+ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
21
+ // If the importer is in node compatibility mode or this is not an ESM
22
+ // file that has been converted to a CommonJS file using a Babel-
23
+ // compatible transform (i.e. "__esModule" has not been set), then set
24
+ // "default" to the CommonJS "module.exports" for node compatibility.
25
+ isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
26
+ mod
27
+ ));
28
+ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
29
+ var targeting_helpers_exports = {};
30
+ __export(targeting_helpers_exports, {
31
+ DEFAULT_RESOLVE_LIST_PAGE_SIZE: () => DEFAULT_RESOLVE_LIST_PAGE_SIZE,
32
+ clearDefaultResolvedListCache: () => clearDefaultResolvedListCache,
33
+ createResolvedListCache: () => createResolvedListCache,
34
+ defaultResolvedListCache: () => defaultResolvedListCache,
35
+ matchesCollectionList: () => matchesCollectionList,
36
+ matchesPropertyList: () => matchesPropertyList,
37
+ resolveCollectionList: () => resolveCollectionList,
38
+ resolvePropertyList: () => resolvePropertyList,
39
+ resolvedListCacheKey: () => resolvedListCacheKey
40
+ });
41
+ module.exports = __toCommonJS(targeting_helpers_exports);
42
+ var import_node_crypto = require("node:crypto");
43
+ var import_promises = require("node:dns/promises");
44
+ var import_mcp = require('../protocols/mcp.js');
45
+ var import_net = require('../net/index.js');
46
+ var import_probe_policy = require('../utils/probe-policy.js');
47
+ var import_pin_and_bind_fetch = require('../net/pin-and-bind-fetch.js');
48
+ var import_response_unwrapper = require('../utils/response-unwrapper.js');
49
+ const DEFAULT_RESOLVE_LIST_PAGE_SIZE = 1e3;
50
+ class MemoryResolvedListCache {
51
+ entries = /* @__PURE__ */ new Map();
52
+ get(key, nowMs = Date.now()) {
53
+ const entry = this.entries.get(key);
54
+ if (!entry) return void 0;
55
+ if (entry.expiresAtMs <= nowMs) {
56
+ this.entries.delete(key);
57
+ return void 0;
58
+ }
59
+ return cloneResolvedList(entry.value);
60
+ }
61
+ set(key, entry) {
62
+ this.entries.set(key, {
63
+ expiresAtMs: entry.expiresAtMs,
64
+ value: cloneResolvedList(entry.value)
65
+ });
66
+ }
67
+ delete(key) {
68
+ return this.entries.delete(key);
69
+ }
70
+ clear() {
71
+ this.entries.clear();
72
+ }
73
+ }
74
+ function createResolvedListCache() {
75
+ return new MemoryResolvedListCache();
76
+ }
77
+ const defaultResolvedListCache = createResolvedListCache();
78
+ function clearDefaultResolvedListCache() {
79
+ defaultResolvedListCache.clear();
80
+ }
81
+ const defaultResolveListFetchBase = (0, import_pin_and_bind_fetch.createPinAndBindFetch)();
82
+ const defaultResolveListFetch = (input, init) => defaultResolveListFetchBase(input, { ...init, redirect: "manual" });
83
+ const defaultResolveListCallTool = (agentUrl, toolName, args, authToken) => (0, import_mcp.callMCPTool)(agentUrl, toolName, args, authToken, [], void 0, void 0, defaultResolveListFetch);
84
+ function resolvedListPayload(result, kind) {
85
+ if (!result || typeof result !== "object" || Array.isArray(result)) return result;
86
+ const envelope = result;
87
+ const isMcp = "structuredContent" in envelope || "content" in envelope || "isError" in envelope;
88
+ let payload;
89
+ try {
90
+ payload = isMcp ? (0, import_response_unwrapper.unwrapProtocolResponse)(envelope, void 0, "mcp") : envelope;
91
+ } catch (cause) {
92
+ throw new Error(`${kind}_list_invalid_response`, { cause });
93
+ }
94
+ const data = payload && typeof payload === "object" ? payload : void 0;
95
+ if (envelope.isError === true || data?.adcp_error !== void 0) {
96
+ throw Object.assign(new Error(`${kind}_list_invalid_response`, { cause: data?.adcp_error }), {
97
+ adcp_error: data?.adcp_error
98
+ });
99
+ }
100
+ return payload;
101
+ }
102
+ async function resolvePropertyList(ref, options = {}) {
103
+ const structurallyNormalizedRef = await normalizePropertyListReference(ref, { resolveDns: false });
104
+ const cache = cacheForOptions(options);
105
+ const nowMs = nowMsForOptions(options);
106
+ const cacheKey = resolvedListCacheKey("property", structurallyNormalizedRef, options);
107
+ const cached = cacheKey && !options.strictResponseValidation ? cache?.get(cacheKey, nowMs) : void 0;
108
+ if (cached) return cached;
109
+ const normalizedRef = options.callTool ? structurallyNormalizedRef : await normalizePropertyListReference(structurallyNormalizedRef, { resolveDns: false });
110
+ const result = await fetchResolvedPropertyList(normalizedRef, options);
111
+ cacheResolvedList(cache, cacheKey, result, nowMs);
112
+ return result;
113
+ }
114
+ async function fetchResolvedPropertyList(ref, options) {
115
+ const callTool = options.callTool ?? defaultResolveListCallTool;
116
+ const identifiers = [];
117
+ let listId;
118
+ let cacheValidUntil;
119
+ let missingCacheValidUntil = false;
120
+ let cursor;
121
+ const seenCursors = /* @__PURE__ */ new Set();
122
+ for (let pageIndex = 0; pageIndex < maxPagesForOptions(options); pageIndex += 1) {
123
+ const args = buildResolveListArgs(ref.list_id, pageSizeForOptions(options), cursor);
124
+ const raw = resolvedListPayload(
125
+ await callTool(ref.agent_url, "get_property_list", args, ref.auth_token),
126
+ "property"
127
+ );
128
+ if (!raw || typeof raw !== "object" || !("list" in raw)) {
129
+ throw new Error("property_list_invalid_response");
130
+ }
131
+ const response = raw;
132
+ if (response.status !== void 0 && response.status !== "completed" || raw.errors !== void 0 && (!Array.isArray(raw.errors) || raw.errors.some((error) => !error || typeof error !== "object" || error.severity !== "warning")) || raw.adcp_error !== void 0 || !Array.isArray(response.identifiers)) {
133
+ throw new Error("property_list_invalid_response");
134
+ }
135
+ if (options.strictResponseValidation) {
136
+ const { GetPropertyListResponseSchema } = await import("../types/schemas.generated.js");
137
+ if (!GetPropertyListResponseSchema.safeParse(raw).success || response.status !== "completed" || response.identifiers.length > pageSizeForOptions(options)) {
138
+ throw new Error("property_list_invalid_response");
139
+ }
140
+ }
141
+ if (!response.list || response.list.list_id !== ref.list_id || response.identifiers !== void 0 && (!Array.isArray(response.identifiers) || response.identifiers.some(
142
+ (identifier) => !identifier || typeof identifier !== "object" || typeof identifier.type !== "string" || typeof identifier.value !== "string"
143
+ ))) {
144
+ throw new Error("property_list_invalid_response");
145
+ }
146
+ listId = response.list.list_id;
147
+ identifiers.push(...response.identifiers ?? []);
148
+ if (typeof response.cache_valid_until === "string") {
149
+ cacheValidUntil = earliestIsoTimestamp(cacheValidUntil, response.cache_valid_until);
150
+ } else {
151
+ missingCacheValidUntil = true;
152
+ }
153
+ const pagination = readPagination(response.pagination);
154
+ if (pagination.invalid) {
155
+ throw new Error("property_list_invalid_pagination");
156
+ }
157
+ if (!pagination.hasMore) {
158
+ return {
159
+ listId,
160
+ agentUrl: ref.agent_url,
161
+ identifiers,
162
+ cacheValidUntil: missingCacheValidUntil ? void 0 : cacheValidUntil
163
+ };
164
+ }
165
+ if (!pagination.cursor) {
166
+ throw new Error("property_list_invalid_pagination");
167
+ }
168
+ if (seenCursors.has(pagination.cursor)) throw new Error("property_list_invalid_pagination");
169
+ seenCursors.add(pagination.cursor);
170
+ cursor = pagination.cursor;
171
+ }
172
+ throw new Error("property_list_pagination_limit_exceeded");
173
+ }
174
+ async function resolveCollectionList(ref, options = {}) {
175
+ const structurallyNormalizedRef = await normalizeCollectionListReference(ref, { resolveDns: false });
176
+ const cache = cacheForOptions(options);
177
+ const nowMs = nowMsForOptions(options);
178
+ const cacheKey = resolvedListCacheKey("collection", structurallyNormalizedRef, options);
179
+ const cached = cacheKey && !options.strictResponseValidation ? cache?.get(cacheKey, nowMs) : void 0;
180
+ if (cached) return cached;
181
+ const normalizedRef = options.callTool ? structurallyNormalizedRef : await normalizeCollectionListReference(structurallyNormalizedRef, { resolveDns: false });
182
+ const result = await fetchResolvedCollectionList(normalizedRef, options);
183
+ cacheResolvedList(cache, cacheKey, result, nowMs);
184
+ return result;
185
+ }
186
+ async function fetchResolvedCollectionList(ref, options) {
187
+ const callTool = options.callTool ?? defaultResolveListCallTool;
188
+ const collections = [];
189
+ let listId;
190
+ let cacheValidUntil;
191
+ let missingCacheValidUntil = false;
192
+ let cursor;
193
+ for (let pageIndex = 0; pageIndex < maxPagesForOptions(options); pageIndex += 1) {
194
+ const args = buildResolveListArgs(ref.list_id, pageSizeForOptions(options), cursor);
195
+ const raw = resolvedListPayload(
196
+ await callTool(ref.agent_url, "get_collection_list", args, ref.auth_token),
197
+ "collection"
198
+ );
199
+ if (!raw || typeof raw !== "object" || !("list" in raw)) {
200
+ throw new Error("collection_list_invalid_response");
201
+ }
202
+ const response = raw;
203
+ if (response.status !== void 0 && response.status !== "completed" || raw.errors !== void 0 && (!Array.isArray(raw.errors) || raw.errors.some((error) => !error || typeof error !== "object" || error.severity !== "warning")) || !response.list || response.list.list_id !== ref.list_id || !Array.isArray(response.collections) || response.collections.some(
204
+ (collection) => !collection || typeof collection !== "object" || Array.isArray(collection) || ["publisher_domain", "collection_id", "collection_rid", "name"].some(
205
+ (field) => field in collection && typeof collection[field] !== "string"
206
+ ) || collection.distribution_ids !== void 0 && (!Array.isArray(collection.distribution_ids) || collection.distribution_ids.some(
207
+ (identifier) => !identifier || typeof identifier !== "object" || typeof identifier.type !== "string" || typeof identifier.value !== "string"
208
+ ))
209
+ )) {
210
+ throw new Error("collection_list_invalid_response");
211
+ }
212
+ if (options.strictResponseValidation) {
213
+ const { GetCollectionListResponseSchema } = await import("../types/schemas.generated.js");
214
+ if (!GetCollectionListResponseSchema.safeParse(raw).success || response.status !== "completed" || response.collections.length > pageSizeForOptions(options)) {
215
+ throw new Error("collection_list_invalid_response");
216
+ }
217
+ }
218
+ listId = response.list.list_id;
219
+ collections.push(...response.collections ?? []);
220
+ if (typeof response.cache_valid_until === "string") {
221
+ cacheValidUntil = earliestIsoTimestamp(cacheValidUntil, response.cache_valid_until);
222
+ } else {
223
+ missingCacheValidUntil = true;
224
+ }
225
+ const pagination = readPagination(response.pagination);
226
+ if (pagination.invalid) {
227
+ throw new Error("collection_list_invalid_pagination");
228
+ }
229
+ if (!pagination.hasMore) {
230
+ return {
231
+ listId,
232
+ agentUrl: ref.agent_url,
233
+ collections,
234
+ cacheValidUntil: missingCacheValidUntil ? void 0 : cacheValidUntil
235
+ };
236
+ }
237
+ if (!pagination.cursor) {
238
+ throw new Error("collection_list_invalid_pagination");
239
+ }
240
+ cursor = pagination.cursor;
241
+ }
242
+ throw new Error("collection_list_pagination_limit_exceeded");
243
+ }
244
+ function resolvedListCacheKey(kind, ref, options = {}) {
245
+ const scope = ref.auth_token ?? options.cacheScopeKey;
246
+ if (!scope) return void 0;
247
+ const material = JSON.stringify({
248
+ kind,
249
+ agent_url: ref.agent_url,
250
+ list_id: ref.list_id,
251
+ scope_sha256: sha256(scope),
252
+ page_size: options.pageSize ?? DEFAULT_RESOLVE_LIST_PAGE_SIZE,
253
+ resolve: true
254
+ });
255
+ return `adcp-resolved-list:${sha256(material)}`;
256
+ }
257
+ async function normalizePropertyListReference(ref, options) {
258
+ return {
259
+ ...ref,
260
+ agent_url: await normalizeListAgentUrl(ref.agent_url, options)
261
+ };
262
+ }
263
+ async function normalizeCollectionListReference(ref, options) {
264
+ return {
265
+ ...ref,
266
+ agent_url: await normalizeListAgentUrl(ref.agent_url, options)
267
+ };
268
+ }
269
+ async function normalizeListAgentUrl(raw, options) {
270
+ let url;
271
+ try {
272
+ url = new URL(raw);
273
+ } catch {
274
+ throw new Error("list_agent_url_invalid");
275
+ }
276
+ if (url.username || url.password || url.search || url.hash) {
277
+ throw new Error("list_agent_url_malformed");
278
+ }
279
+ const allowInternal = (0, import_probe_policy.isInternalProbesAllowed)();
280
+ if (url.protocol !== "https:" && !(allowInternal && url.protocol === "http:")) {
281
+ throw new Error("list_agent_url_insecure");
282
+ }
283
+ const hostname = url.hostname.replace(/^\[|\]$/g, "");
284
+ if ((0, import_net.isAlwaysBlocked)(hostname)) {
285
+ throw new Error("list_agent_url_always_blocked");
286
+ }
287
+ if (!allowInternal && (0, import_net.isPrivateIp)(hostname)) {
288
+ throw new Error("list_agent_url_private_address");
289
+ }
290
+ if (options.resolveDns) {
291
+ let addresses;
292
+ try {
293
+ addresses = await (0, import_promises.lookup)(hostname, { all: true });
294
+ } catch {
295
+ throw new Error("list_agent_url_dns_failed");
296
+ }
297
+ if (addresses.length === 0) {
298
+ throw new Error("list_agent_url_dns_empty");
299
+ }
300
+ for (const { address } of addresses) {
301
+ if ((0, import_net.isAlwaysBlocked)(address)) {
302
+ throw new Error("list_agent_url_always_blocked");
303
+ }
304
+ if (!allowInternal && (0, import_net.isPrivateIp)(address)) {
305
+ throw new Error("list_agent_url_private_address");
306
+ }
307
+ }
308
+ }
309
+ return url.toString();
310
+ }
311
+ function buildResolveListArgs(listId, pageSize, cursor) {
312
+ const args = {
313
+ list_id: listId,
314
+ resolve: true
315
+ };
316
+ const pagination = {};
317
+ pagination.max_results = pageSize;
318
+ if (cursor) pagination.cursor = cursor;
319
+ if (Object.keys(pagination).length > 0) args.pagination = pagination;
320
+ return args;
321
+ }
322
+ function cacheForOptions(options) {
323
+ if (options.callTool && options.cache === void 0) return void 0;
324
+ return options.cache === false ? void 0 : options.cache ?? defaultResolvedListCache;
325
+ }
326
+ function cacheResolvedList(cache, cacheKey, value, nowMs) {
327
+ if (!cache || !cacheKey || !value.cacheValidUntil) return;
328
+ const expiresAtMs = Date.parse(value.cacheValidUntil);
329
+ if (!Number.isFinite(expiresAtMs) || expiresAtMs <= nowMs) return;
330
+ cache.set(cacheKey, { value, expiresAtMs });
331
+ }
332
+ function nowMsForOptions(options) {
333
+ const now = options.now?.();
334
+ if (now instanceof Date) return now.getTime();
335
+ if (typeof now === "number") return now;
336
+ return Date.now();
337
+ }
338
+ function maxPagesForOptions(options) {
339
+ return options.maxPages ?? 100;
340
+ }
341
+ function pageSizeForOptions(options) {
342
+ return options.pageSize ?? DEFAULT_RESOLVE_LIST_PAGE_SIZE;
343
+ }
344
+ function readPagination(value) {
345
+ if (!value || typeof value !== "object" || Array.isArray(value)) return { hasMore: false, invalid: false };
346
+ const pagination = value;
347
+ const cursor = typeof pagination.cursor === "string" && pagination.cursor.length > 0 ? pagination.cursor : void 0;
348
+ const invalid = pagination.has_more !== void 0 && typeof pagination.has_more !== "boolean" || cursor !== void 0 && pagination.has_more !== true;
349
+ return {
350
+ hasMore: pagination.has_more === true,
351
+ cursor,
352
+ invalid
353
+ };
354
+ }
355
+ function earliestIsoTimestamp(current, next) {
356
+ if (!current) return next;
357
+ const currentMs = Date.parse(current);
358
+ const nextMs = Date.parse(next);
359
+ if (!Number.isFinite(currentMs)) return next;
360
+ if (!Number.isFinite(nextMs)) return current;
361
+ return nextMs < currentMs ? next : current;
362
+ }
363
+ function cloneResolvedList(value) {
364
+ return structuredClone(value);
365
+ }
366
+ function sha256(value) {
367
+ return (0, import_node_crypto.createHash)("sha256").update(value, "utf8").digest("hex");
368
+ }
369
+ function matchesPropertyList(property, list) {
370
+ return list.identifiers.some((entry) => identifiersMatch(property, entry));
371
+ }
372
+ function identifiersMatch(property, entry) {
373
+ if (property.type !== entry.type) return false;
374
+ if (property.type !== "domain") {
375
+ return property.value === entry.value;
376
+ }
377
+ return domainMatches(property.value, entry.value);
378
+ }
379
+ function domainMatches(candidate, pattern) {
380
+ const c = candidate.toLowerCase();
381
+ const p = pattern.toLowerCase();
382
+ if (c === p) return true;
383
+ if (p.startsWith("*.")) {
384
+ const suffix = p.slice(1);
385
+ return c.endsWith(suffix) && c !== p.slice(2);
386
+ }
387
+ return c === `www.${p}` || c === `m.${p}`;
388
+ }
389
+ function matchesCollectionList(collection, list) {
390
+ return list.collections.some((entry) => collectionsMatch(collection, entry));
391
+ }
392
+ function collectionsMatch(a, b) {
393
+ if (a.collection_rid && b.collection_rid && a.collection_rid === b.collection_rid) {
394
+ return true;
395
+ }
396
+ if (!a.distribution_ids?.length || !b.distribution_ids?.length) return false;
397
+ return a.distribution_ids.some(
398
+ (aid) => b.distribution_ids.some((bid) => aid.type === bid.type && aid.value === bid.value)
399
+ );
400
+ }
401
+ // Annotate the CommonJS export names for ESM import in node:
402
+ 0 && (module.exports = {
403
+ DEFAULT_RESOLVE_LIST_PAGE_SIZE,
404
+ clearDefaultResolvedListCache,
405
+ createResolvedListCache,
406
+ defaultResolvedListCache,
407
+ matchesCollectionList,
408
+ matchesPropertyList,
409
+ resolveCollectionList,
410
+ resolvePropertyList,
411
+ resolvedListCacheKey
412
+ });