@adcp/sdk 16.0.0-beta.7 → 16.0.0-beta.9

package/dist/lib/server/decisioning/specialisms/lists.d.mts

@@ -21,7 +21,7 @@
  * one-time fetch token sellers store in their secret manager; `delete_*`
  * revokes the token. Tokens are scoped per-seller for revocation.
  *
- * Status: Preview / 6.0.
+ * For standalone list-token reads, use registerPropertyListTool from @adcp/sdk/server.
  *
  * @public
  */
@@ -42,19 +42,19 @@ export type ListCollectionListsPayload = ServerPayload<ListCollectionListsRespon
 export type DeleteCollectionListPayload = ServerPayload<DeleteCollectionListResponse>;
 export interface PropertyListsPlatform<TCtxMeta = Record<string, unknown>> {
     /**
-     * Create a property list. Returns a `fetch_token` the buyer stores in
+     * Create a property list. Returns an `auth_token` the buyer stores in
      * their secret manager. Token is scoped to this list_id; MUST NOT be
      * reused across lists.
      */
     createPropertyList(req: CreatePropertyListRequest, ctx: Ctx<TCtxMeta>): Promise<CreatePropertyListPayload>;
     /** Patch an existing property list. */
     updatePropertyList(req: UpdatePropertyListRequest, ctx: Ctx<TCtxMeta>): Promise<UpdatePropertyListPayload>;
-    /** Read a property list by id. Sellers call this with the fetch_token. */
+    /** Read a property list by id. Sellers call this with the auth_token. */
     getPropertyList(req: GetPropertyListRequest, ctx: Ctx<TCtxMeta>): Promise<GetPropertyListPayload>;
     /** Discover property lists the caller is authorized to read. */
     listPropertyLists(req: ListPropertyListsRequest, ctx: Ctx<TCtxMeta>): Promise<ListPropertyListsPayload>;
     /**
-     * Delete a property list. MUST revoke the fetch_token immediately and
+     * Delete a property list. MUST revoke the auth_token immediately and
      * signal cache invalidation to sellers (reduced cache_valid_until or
      * a list-changed webhook). Compromise-driven revocation MUST also
      * trigger this path.

package/dist/lib/server/decisioning/specialisms/lists.d.ts

@@ -21,7 +21,7 @@
  * one-time fetch token sellers store in their secret manager; `delete_*`
  * revokes the token. Tokens are scoped per-seller for revocation.
  *
- * Status: Preview / 6.0.
+ * For standalone list-token reads, use registerPropertyListTool from @adcp/sdk/server.
  *
  * @public
  */
@@ -42,19 +42,19 @@ export type ListCollectionListsPayload = ServerPayload<ListCollectionListsRespon
 export type DeleteCollectionListPayload = ServerPayload<DeleteCollectionListResponse>;
 export interface PropertyListsPlatform<TCtxMeta = Record<string, unknown>> {
     /**
-     * Create a property list. Returns a `fetch_token` the buyer stores in
+     * Create a property list. Returns an `auth_token` the buyer stores in
      * their secret manager. Token is scoped to this list_id; MUST NOT be
      * reused across lists.
      */
     createPropertyList(req: CreatePropertyListRequest, ctx: Ctx<TCtxMeta>): Promise<CreatePropertyListPayload>;
     /** Patch an existing property list. */
     updatePropertyList(req: UpdatePropertyListRequest, ctx: Ctx<TCtxMeta>): Promise<UpdatePropertyListPayload>;
-    /** Read a property list by id. Sellers call this with the fetch_token. */
+    /** Read a property list by id. Sellers call this with the auth_token. */
     getPropertyList(req: GetPropertyListRequest, ctx: Ctx<TCtxMeta>): Promise<GetPropertyListPayload>;
     /** Discover property lists the caller is authorized to read. */
     listPropertyLists(req: ListPropertyListsRequest, ctx: Ctx<TCtxMeta>): Promise<ListPropertyListsPayload>;
     /**
-     * Delete a property list. MUST revoke the fetch_token immediately and
+     * Delete a property list. MUST revoke the auth_token immediately and
      * signal cache invalidation to sellers (reduced cache_valid_until or
      * a list-changed webhook). Compromise-driven revocation MUST also
      * trigger this path.

package/dist/lib/server/index.d.mts

@@ -105,3 +105,6 @@ export { createDerivedAccountStore, type DerivedAccountStoreOptions, type Derive
 export { ConformanceClient, WebSocketTransport, type ConformanceClientOptions, type ConformanceStatus, } from './socket-mode/index.mjs';
 export { mediaBuyActionResolver } from './media-buy-action-resolver.mjs';
 export type { SellerActionDecision, SellerActionResolutionOptions, SellerActionResolution, } from './media-buy-action-resolver.mjs';
+export * from '../identifiers.mjs';
+export { registerPropertyListTool, sendPropertyListChanged } from './property-lists.mjs';
+export type { PropertyListPage, PropertyListToolOptions, PropertyListChangedNotification, SendPropertyListChangedOptions, } from './property-lists.mjs';

package/dist/lib/server/index.d.ts

@@ -105,3 +105,6 @@ export { createDerivedAccountStore, type DerivedAccountStoreOptions, type Derive
 export { ConformanceClient, WebSocketTransport, type ConformanceClientOptions, type ConformanceStatus, } from './socket-mode';
 export { mediaBuyActionResolver } from './media-buy-action-resolver';
 export type { SellerActionDecision, SellerActionResolutionOptions, SellerActionResolution, } from './media-buy-action-resolver';
+export * from '../identifiers';
+export { registerPropertyListTool, sendPropertyListChanged } from './property-lists';
+export type { PropertyListPage, PropertyListToolOptions, PropertyListChangedNotification, SendPropertyListChangedOptions, } from './property-lists';

package/dist/lib/server/index.js

@@ -254,6 +254,7 @@ __export(server_exports, {
   redisWebhookDeliveryRecoveryBackend: () => import_webhook_delivery.redisWebhookDeliveryRecoveryBackend,
   redisWebhookDeliveryStore: () => import_webhook_delivery.redisWebhookDeliveryStore,
   registerAdcpTaskTool: () => import_tasks.registerAdcpTaskTool,
+  registerPropertyListTool: () => import_property_lists.registerPropertyListTool,
   registerTestController: () => import_test_controller.registerTestController,
   replaceAccountFinancialsIfSeeded: () => import_test_controller_bridge.replaceAccountFinancialsIfSeeded,
   requireAuthenticatedOrSigned: () => import_auth_signature.requireAuthenticatedOrSigned,
@@ -269,6 +270,7 @@ __export(server_exports, {
   scopeCtxMetadataKey: () => import_ctx_metadata.scopeCtxMetadataKey,
   scopedStore: () => import_state_store.scopedStore,
   scrubExtensions: () => import_wire_safe.scrubExtensions,
+  sendPropertyListChanged: () => import_property_lists.sendPropertyListChanged,
   serve: () => import_serve.serve,
   signatureErrorCodeFromCause: () => import_auth.signatureErrorCodeFromCause,
   stripCtxMetadata: () => import_ctx_metadata.stripCtxMetadata,
@@ -353,6 +355,8 @@ var import_keyed_account_backend = require('../adapters/keyed-account-backend.js
 var import_derived_account_store = require('../adapters/derived-account-store.js');
 var import_socket_mode = require('./socket-mode/index.js');
 var import_media_buy_action_resolver = require('./media-buy-action-resolver.js');
+__reExport(server_exports, require('../identifiers.js'), module.exports);
+var import_property_lists = require('./property-lists.js');
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   A2AInvocationError,
@@ -590,6 +594,7 @@ var import_media_buy_action_resolver = require('./media-buy-action-resolver.js')
   redisWebhookDeliveryRecoveryBackend,
   redisWebhookDeliveryStore,
   registerAdcpTaskTool,
+  registerPropertyListTool,
   registerTestController,
   replaceAccountFinancialsIfSeeded,
   requireAuthenticatedOrSigned,
@@ -605,6 +610,7 @@ var import_media_buy_action_resolver = require('./media-buy-action-resolver.js')
   scopeCtxMetadataKey,
   scopedStore,
   scrubExtensions,
+  sendPropertyListChanged,
   serve,
   signatureErrorCodeFromCause,
   stripCtxMetadata,
@@ -631,5 +637,6 @@ var import_media_buy_action_resolver = require('./media-buy-action-resolver.js')
   verifyProposalTermsDigest,
   verifySignatureAsAuthenticator,
   wrapEnvelope,
-  ...require('./decisioning/index.js')
+  ...require('./decisioning/index.js'),
+  ...require('../identifiers.js')
 });

package/dist/lib/server/index.mjs

@@ -302,6 +302,8 @@ import {
   WebSocketTransport
 } from "./socket-mode/index.mjs";
 import { mediaBuyActionResolver } from "./media-buy-action-resolver.mjs";
+export * from "../identifiers.mjs";
+import { registerPropertyListTool, sendPropertyListChanged } from "./property-lists.mjs";
 export {
   A2AInvocationError,
   ACCOUNT_NOTIFICATION_TYPES,
@@ -538,6 +540,7 @@ export {
   redisWebhookDeliveryRecoveryBackend,
   redisWebhookDeliveryStore,
   registerAdcpTaskTool,
+  registerPropertyListTool,
   registerTestController,
   replaceAccountFinancialsIfSeeded,
   requireAuthenticatedOrSigned,
@@ -553,6 +556,7 @@ export {
   scopeCtxMetadataKey,
   scopedStore,
   scrubExtensions,
+  sendPropertyListChanged,
   serve,
   signatureErrorCodeFromCause,
   stripCtxMetadata,

package/dist/lib/server/property-lists.d.mts

@@ -0,0 +1,36 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { GetPropertyListRequest, GetPropertyListResponse } from '../types/tools.generated.mjs';
+import type { WebhookEmitter, WebhookEmitParams, WebhookEmitResult } from './webhook-emitter.mjs';
+export type PropertyListPage = Pick<GetPropertyListResponse, 'list' | 'identifiers' | 'pagination' | 'resolved_at' | 'cache_valid_until' | 'coverage_gaps'>;
+export interface PropertyListToolOptions<TPrincipal> {
+    /** Verify this token's access to this exact list on every request/page. Return null/false to deny access. */
+    verifyToken: (input: {
+        listId: string;
+        token: string;
+    }) => TPrincipal | null | false | Promise<TPrincipal | null | false>;
+    /** Load an authorized page. Honor resolve:false without resolving identifiers. Cursors must be bound to the list and principal. */
+    loadPage: (request: GetPropertyListRequest, principal: TPrincipal) => Promise<PropertyListPage>;
+}
+/**
+ * Register a read-only MCP tool using per-list tokens, independently of normal
+ * platform account credentials. Tokens arrive through Authorization: Bearer
+ * or x-adcp-auth, never tool arguments. Mount on an MCP endpoint whose HTTP
+ * auth layer permits list tokens through to this verifier.
+ */
+export declare function registerPropertyListTool<TPrincipal>(server: McpServer, options: PropertyListToolOptions<TPrincipal>): import("@modelcontextprotocol/sdk/server/mcp.js").RegisteredTool;
+export interface PropertyListChangedNotification {
+    list_id: string;
+    list_name?: string;
+    resolved_at: string;
+    cache_valid_until?: string;
+    change_summary?: {
+        properties_added?: number;
+        properties_removed?: number;
+        total_properties?: number;
+    };
+}
+export type SendPropertyListChangedOptions = Pick<WebhookEmitParams, 'url' | 'delivery_id' | 'retries' | 'attemptAuthorizationContext'> & {
+    notification: PropertyListChangedNotification;
+};
+/** Send a summary-only notification through the SDK's signed, retrying delivery kernel. Reuse delivery_id and notification for retries. */
+export declare function sendPropertyListChanged(emitter: WebhookEmitter, options: SendPropertyListChangedOptions): Promise<WebhookEmitResult>;

package/dist/lib/server/property-lists.d.ts

@@ -0,0 +1,36 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { GetPropertyListRequest, GetPropertyListResponse } from '../types/tools.generated';
+import type { WebhookEmitter, WebhookEmitParams, WebhookEmitResult } from './webhook-emitter';
+export type PropertyListPage = Pick<GetPropertyListResponse, 'list' | 'identifiers' | 'pagination' | 'resolved_at' | 'cache_valid_until' | 'coverage_gaps'>;
+export interface PropertyListToolOptions<TPrincipal> {
+    /** Verify this token's access to this exact list on every request/page. Return null/false to deny access. */
+    verifyToken: (input: {
+        listId: string;
+        token: string;
+    }) => TPrincipal | null | false | Promise<TPrincipal | null | false>;
+    /** Load an authorized page. Honor resolve:false without resolving identifiers. Cursors must be bound to the list and principal. */
+    loadPage: (request: GetPropertyListRequest, principal: TPrincipal) => Promise<PropertyListPage>;
+}
+/**
+ * Register a read-only MCP tool using per-list tokens, independently of normal
+ * platform account credentials. Tokens arrive through Authorization: Bearer
+ * or x-adcp-auth, never tool arguments. Mount on an MCP endpoint whose HTTP
+ * auth layer permits list tokens through to this verifier.
+ */
+export declare function registerPropertyListTool<TPrincipal>(server: McpServer, options: PropertyListToolOptions<TPrincipal>): import("@modelcontextprotocol/sdk/server/mcp.js").RegisteredTool;
+export interface PropertyListChangedNotification {
+    list_id: string;
+    list_name?: string;
+    resolved_at: string;
+    cache_valid_until?: string;
+    change_summary?: {
+        properties_added?: number;
+        properties_removed?: number;
+        total_properties?: number;
+    };
+}
+export type SendPropertyListChangedOptions = Pick<WebhookEmitParams, 'url' | 'delivery_id' | 'retries' | 'attemptAuthorizationContext'> & {
+    notification: PropertyListChangedNotification;
+};
+/** Send a summary-only notification through the SDK's signed, retrying delivery kernel. Reuse delivery_id and notification for retries. */
+export declare function sendPropertyListChanged(emitter: WebhookEmitter, options: SendPropertyListChangedOptions): Promise<WebhookEmitResult>;

package/dist/lib/server/property-lists.js

@@ -0,0 +1,154 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var property_lists_exports = {};
+__export(property_lists_exports, {
+  registerPropertyListTool: () => registerPropertyListTool,
+  sendPropertyListChanged: () => sendPropertyListChanged
+});
+module.exports = __toCommonJS(property_lists_exports);
+var import_zod = require("zod");
+var import_schemas = require('../types/schemas.generated.js');
+var import_wire_shape = require('./ctx-metadata/wire-shape.js');
+function registerPropertyListTool(server, options) {
+  return server.registerTool(
+    "get_property_list",
+    {
+      description: "Retrieve an authorized property list and a page of resolved identifiers.",
+      inputSchema: import_schemas.GetPropertyListRequestSchema,
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }
+    },
+    async (request, extra) => {
+      const denied = () => toolError("PERMISSION_DENIED", "Property list access denied.", request.context);
+      const headers = extra.requestInfo?.headers ?? {};
+      for (const name of ["authorization", "x-adcp-auth"]) {
+        const values = Object.entries(headers).filter(([key]) => key.toLowerCase() === name);
+        if (values.length > 1 || values.length === 1 && typeof values[0][1] !== "string") return denied();
+      }
+      const readHeader = (name) => {
+        const values = Object.entries(headers).filter(([key]) => key.toLowerCase() === name);
+        if (values.length !== 1 || typeof values[0][1] !== "string") return void 0;
+        return values[0][1];
+      };
+      const authorization = readHeader("authorization");
+      const bearer = authorization?.match(/^Bearer ([^\s]+)$/i)?.[1];
+      const adcpToken = readHeader("x-adcp-auth");
+      const authenticatedToken = extra.authInfo?.token;
+      const tokens = [bearer, adcpToken, authenticatedToken].filter((token) => token !== void 0);
+      if (!tokens.length || tokens.some((token) => !token || token !== tokens[0]) || authorization !== void 0 && !bearer)
+        return denied();
+      let principal;
+      try {
+        principal = await options.verifyToken({ listId: request.list_id, token: tokens[0] });
+      } catch {
+        return denied();
+      }
+      if (principal === null || principal === false || principal === void 0) return denied();
+      try {
+        const page = await options.loadPage(request, principal);
+        if (page.list.list_id !== request.list_id) throw new Error("Invalid list identity");
+        if (request.resolve !== false && !Array.isArray(page.identifiers))
+          throw new Error("Missing resolved identifiers");
+        const limit = request.pagination?.max_results ?? 1e3;
+        if (request.resolve !== false && (page.identifiers?.length ?? 0) > limit) throw new Error("Invalid page size");
+        if (page.pagination?.has_more && !page.pagination.cursor) throw new Error("Missing continuation cursor");
+        if (!page.pagination?.has_more && page.pagination?.cursor) throw new Error("Unexpected continuation cursor");
+        const payload = import_schemas.GetPropertyListResponseSchema.parse({
+          list: Object.fromEntries(
+            [
+              "list_id",
+              "name",
+              "description",
+              "account",
+              "base_properties",
+              "filters",
+              "brand",
+              "webhook_url",
+              "cache_duration_hours",
+              "created_at",
+              "updated_at",
+              "property_count",
+              "pricing_options"
+            ].filter((key) => Object.hasOwn(page.list, key)).map((key) => [key, page.list[key]])
+          ),
+          ...page.identifiers !== void 0 ? { identifiers: page.identifiers.map((identifier) => ({ type: identifier.type, value: identifier.value })) } : {},
+          ...page.pagination !== void 0 ? {
+            pagination: {
+              has_more: page.pagination.has_more,
+              cursor: page.pagination.cursor,
+              total_count: page.pagination.total_count
+            }
+          } : {},
+          ...page.resolved_at !== void 0 ? { resolved_at: page.resolved_at } : {},
+          ...page.cache_valid_until !== void 0 ? { cache_valid_until: page.cache_valid_until } : {},
+          ...page.coverage_gaps !== void 0 ? { coverage_gaps: page.coverage_gaps } : {},
+          status: "completed",
+          ...request.resolve === false ? { identifiers: void 0, pagination: void 0 } : {},
+          ...request.context ? { context: request.context } : {}
+        });
+        (0, import_wire_shape.stripCtxMetadata)({ property_list: payload.list });
+        return { content: [{ type: "text", text: JSON.stringify(payload) }], structuredContent: payload };
+      } catch {
+        return toolError("INTERNAL_ERROR", "Property list could not be loaded.", request.context);
+      }
+    }
+  );
+}
+function toolError(code, message, context) {
+  const payload = { status: "failed", errors: [{ code, message }], ...context !== void 0 ? { context } : {} };
+  return {
+    isError: true,
+    content: [{ type: "text", text: JSON.stringify(payload) }],
+    structuredContent: payload
+  };
+}
+async function sendPropertyListChanged(emitter, options) {
+  const { notification, ...delivery } = options;
+  const dateTime = import_zod.z.string().datetime({ offset: true });
+  if (!notification.list_id || !dateTime.safeParse(notification.resolved_at).success || notification.cache_valid_until !== void 0 && !dateTime.safeParse(notification.cache_valid_until).success) {
+    throw new TypeError("Property-list notifications require a list_id and valid timestamps");
+  }
+  const summary = notification.change_summary === void 0 ? void 0 : Object.fromEntries(
+    ["properties_added", "properties_removed", "total_properties"].filter(
+      (key) => Object.hasOwn(notification.change_summary, key) && notification.change_summary[key] !== void 0
+    ).map((key) => [key, notification.change_summary[key]])
+  );
+  for (const count of Object.values(summary ?? {})) {
+    if (typeof count !== "number" || !Number.isSafeInteger(count) || count < 0)
+      throw new TypeError("Property-list change counts must be nonnegative integers");
+  }
+  return emitter.emit({
+    ...delivery,
+    authentication: null,
+    signingProfile: "adcp/webhook-signing/v1",
+    payload: {
+      event: "property_list_changed",
+      list_id: notification.list_id,
+      resolved_at: notification.resolved_at,
+      ...notification.list_name !== void 0 ? { list_name: notification.list_name } : {},
+      ...notification.cache_valid_until !== void 0 ? { cache_valid_until: notification.cache_valid_until } : {},
+      ...summary !== void 0 ? { change_summary: summary } : {},
+      signature: "rfc9421"
+    }
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  registerPropertyListTool,
+  sendPropertyListChanged
+});

package/dist/lib/server/property-lists.mjs

@@ -0,0 +1,129 @@
+import { z } from "zod";
+import { GetPropertyListRequestSchema, GetPropertyListResponseSchema } from "../types/schemas.generated.mjs";
+import { stripCtxMetadata } from "./ctx-metadata/wire-shape.mjs";
+function registerPropertyListTool(server, options) {
+  return server.registerTool(
+    "get_property_list",
+    {
+      description: "Retrieve an authorized property list and a page of resolved identifiers.",
+      inputSchema: GetPropertyListRequestSchema,
+      annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true }
+    },
+    async (request, extra) => {
+      const denied = () => toolError("PERMISSION_DENIED", "Property list access denied.", request.context);
+      const headers = extra.requestInfo?.headers ?? {};
+      for (const name of ["authorization", "x-adcp-auth"]) {
+        const values = Object.entries(headers).filter(([key]) => key.toLowerCase() === name);
+        if (values.length > 1 || values.length === 1 && typeof values[0][1] !== "string") return denied();
+      }
+      const readHeader = (name) => {
+        const values = Object.entries(headers).filter(([key]) => key.toLowerCase() === name);
+        if (values.length !== 1 || typeof values[0][1] !== "string") return void 0;
+        return values[0][1];
+      };
+      const authorization = readHeader("authorization");
+      const bearer = authorization?.match(/^Bearer ([^\s]+)$/i)?.[1];
+      const adcpToken = readHeader("x-adcp-auth");
+      const authenticatedToken = extra.authInfo?.token;
+      const tokens = [bearer, adcpToken, authenticatedToken].filter((token) => token !== void 0);
+      if (!tokens.length || tokens.some((token) => !token || token !== tokens[0]) || authorization !== void 0 && !bearer)
+        return denied();
+      let principal;
+      try {
+        principal = await options.verifyToken({ listId: request.list_id, token: tokens[0] });
+      } catch {
+        return denied();
+      }
+      if (principal === null || principal === false || principal === void 0) return denied();
+      try {
+        const page = await options.loadPage(request, principal);
+        if (page.list.list_id !== request.list_id) throw new Error("Invalid list identity");
+        if (request.resolve !== false && !Array.isArray(page.identifiers))
+          throw new Error("Missing resolved identifiers");
+        const limit = request.pagination?.max_results ?? 1e3;
+        if (request.resolve !== false && (page.identifiers?.length ?? 0) > limit) throw new Error("Invalid page size");
+        if (page.pagination?.has_more && !page.pagination.cursor) throw new Error("Missing continuation cursor");
+        if (!page.pagination?.has_more && page.pagination?.cursor) throw new Error("Unexpected continuation cursor");
+        const payload = GetPropertyListResponseSchema.parse({
+          list: Object.fromEntries(
+            [
+              "list_id",
+              "name",
+              "description",
+              "account",
+              "base_properties",
+              "filters",
+              "brand",
+              "webhook_url",
+              "cache_duration_hours",
+              "created_at",
+              "updated_at",
+              "property_count",
+              "pricing_options"
+            ].filter((key) => Object.hasOwn(page.list, key)).map((key) => [key, page.list[key]])
+          ),
+          ...page.identifiers !== void 0 ? { identifiers: page.identifiers.map((identifier) => ({ type: identifier.type, value: identifier.value })) } : {},
+          ...page.pagination !== void 0 ? {
+            pagination: {
+              has_more: page.pagination.has_more,
+              cursor: page.pagination.cursor,
+              total_count: page.pagination.total_count
+            }
+          } : {},
+          ...page.resolved_at !== void 0 ? { resolved_at: page.resolved_at } : {},
+          ...page.cache_valid_until !== void 0 ? { cache_valid_until: page.cache_valid_until } : {},
+          ...page.coverage_gaps !== void 0 ? { coverage_gaps: page.coverage_gaps } : {},
+          status: "completed",
+          ...request.resolve === false ? { identifiers: void 0, pagination: void 0 } : {},
+          ...request.context ? { context: request.context } : {}
+        });
+        stripCtxMetadata({ property_list: payload.list });
+        return { content: [{ type: "text", text: JSON.stringify(payload) }], structuredContent: payload };
+      } catch {
+        return toolError("INTERNAL_ERROR", "Property list could not be loaded.", request.context);
+      }
+    }
+  );
+}
+function toolError(code, message, context) {
+  const payload = { status: "failed", errors: [{ code, message }], ...context !== void 0 ? { context } : {} };
+  return {
+    isError: true,
+    content: [{ type: "text", text: JSON.stringify(payload) }],
+    structuredContent: payload
+  };
+}
+async function sendPropertyListChanged(emitter, options) {
+  const { notification, ...delivery } = options;
+  const dateTime = z.string().datetime({ offset: true });
+  if (!notification.list_id || !dateTime.safeParse(notification.resolved_at).success || notification.cache_valid_until !== void 0 && !dateTime.safeParse(notification.cache_valid_until).success) {
+    throw new TypeError("Property-list notifications require a list_id and valid timestamps");
+  }
+  const summary = notification.change_summary === void 0 ? void 0 : Object.fromEntries(
+    ["properties_added", "properties_removed", "total_properties"].filter(
+      (key) => Object.hasOwn(notification.change_summary, key) && notification.change_summary[key] !== void 0
+    ).map((key) => [key, notification.change_summary[key]])
+  );
+  for (const count of Object.values(summary ?? {})) {
+    if (typeof count !== "number" || !Number.isSafeInteger(count) || count < 0)
+      throw new TypeError("Property-list change counts must be nonnegative integers");
+  }
+  return emitter.emit({
+    ...delivery,
+    authentication: null,
+    signingProfile: "adcp/webhook-signing/v1",
+    payload: {
+      event: "property_list_changed",
+      list_id: notification.list_id,
+      resolved_at: notification.resolved_at,
+      ...notification.list_name !== void 0 ? { list_name: notification.list_name } : {},
+      ...notification.cache_valid_until !== void 0 ? { cache_valid_until: notification.cache_valid_until } : {},
+      ...summary !== void 0 ? { change_summary: summary } : {},
+      signature: "rfc9421"
+    }
+  });
+}
+export {
+  registerPropertyListTool,
+  sendPropertyListChanged
+};

package/dist/lib/server/targeting-helpers.d.mts

@@ -56,6 +56,8 @@ export declare const defaultResolvedListCache: ResolvedListCache;
 export declare function clearDefaultResolvedListCache(): void;
 export type ResolveListCallTool = (agentUrl: string, toolName: 'get_property_list' | 'get_collection_list', args: Record<string, unknown>, authToken?: string) => Promise<unknown>;
 export interface ResolveListOptions {
+    /** Require schema-valid property-list pages with identifiers when resolving. Used for certification. */
+    strictResponseValidation?: boolean;
     /** Maximum page size when calling get_property_list / get_collection_list. Defaults to 1000. */
     pageSize?: number;
     /** Maximum number of pages to walk before treating pagination as unsafe. Defaults to 100. */

package/dist/lib/server/targeting-helpers.d.ts

@@ -56,6 +56,8 @@ export declare const defaultResolvedListCache: ResolvedListCache;
 export declare function clearDefaultResolvedListCache(): void;
 export type ResolveListCallTool = (agentUrl: string, toolName: 'get_property_list' | 'get_collection_list', args: Record<string, unknown>, authToken?: string) => Promise<unknown>;
 export interface ResolveListOptions {
+    /** Require schema-valid property-list pages with identifiers when resolving. Used for certification. */
+    strictResponseValidation?: boolean;
     /** Maximum page size when calling get_property_list / get_collection_list. Defaults to 1000. */
     pageSize?: number;
     /** Maximum number of pages to walk before treating pagination as unsafe. Defaults to 100. */

package/dist/lib/server/targeting-helpers.js

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,6 +17,14 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var targeting_helpers_exports = {};
 __export(targeting_helpers_exports, {
@@ -75,7 +85,7 @@ async function resolvePropertyList(ref, options = {}) {
   const cache = cacheForOptions(options);
   const nowMs = nowMsForOptions(options);
   const cacheKey = resolvedListCacheKey("property", structurallyNormalizedRef, options);
-  const cached = cacheKey ? cache?.get(cacheKey, nowMs) : void 0;
+  const cached = cacheKey && !options.strictResponseValidation ? cache?.get(cacheKey, nowMs) : void 0;
   if (cached) return cached;
   const normalizedRef = options.callTool ? structurallyNormalizedRef : await normalizePropertyListReference(structurallyNormalizedRef, { resolveDns: false });
   const result = await fetchResolvedPropertyList(normalizedRef, options);
@@ -89,6 +99,7 @@ async function fetchResolvedPropertyList(ref, options) {
   let cacheValidUntil;
   let missingCacheValidUntil = false;
   let cursor;
+  const seenCursors = /* @__PURE__ */ new Set();
   for (let pageIndex = 0; pageIndex < maxPagesForOptions(options); pageIndex += 1) {
     const args = buildResolveListArgs(ref.list_id, pageSizeForOptions(options), cursor);
     const raw = await callTool(ref.agent_url, "get_property_list", args, ref.auth_token);
@@ -96,6 +107,20 @@ async function fetchResolvedPropertyList(ref, options) {
       throw new Error("property_list_invalid_response");
     }
     const response = raw;
+    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)) {
+      throw new Error("property_list_invalid_response");
+    }
+    if (options.strictResponseValidation) {
+      const { GetPropertyListResponseSchema } = await import("../types/schemas.generated.js");
+      if (!GetPropertyListResponseSchema.safeParse(raw).success || response.status !== "completed" || response.identifiers.length > pageSizeForOptions(options)) {
+        throw new Error("property_list_invalid_response");
+      }
+    }
+    if (!response.list || response.list.list_id !== ref.list_id || response.identifiers !== void 0 && (!Array.isArray(response.identifiers) || response.identifiers.some(
+      (identifier) => !identifier || typeof identifier !== "object" || typeof identifier.type !== "string" || typeof identifier.value !== "string"
+    ))) {
+      throw new Error("property_list_invalid_response");
+    }
     listId = response.list.list_id;
     identifiers.push(...response.identifiers ?? []);
     if (typeof response.cache_valid_until === "string") {
@@ -118,6 +143,8 @@ async function fetchResolvedPropertyList(ref, options) {
     if (!pagination.cursor) {
       throw new Error("property_list_invalid_pagination");
     }
+    if (seenCursors.has(pagination.cursor)) throw new Error("property_list_invalid_pagination");
+    seenCursors.add(pagination.cursor);
     cursor = pagination.cursor;
   }
   throw new Error("property_list_pagination_limit_exceeded");

package/dist/lib/server/targeting-helpers.mjs

@@ -44,7 +44,7 @@ async function resolvePropertyList(ref, options = {}) {
   const cache = cacheForOptions(options);
   const nowMs = nowMsForOptions(options);
   const cacheKey = resolvedListCacheKey("property", structurallyNormalizedRef, options);
-  const cached = cacheKey ? cache?.get(cacheKey, nowMs) : void 0;
+  const cached = cacheKey && !options.strictResponseValidation ? cache?.get(cacheKey, nowMs) : void 0;
   if (cached) return cached;
   const normalizedRef = options.callTool ? structurallyNormalizedRef : await normalizePropertyListReference(structurallyNormalizedRef, { resolveDns: false });
   const result = await fetchResolvedPropertyList(normalizedRef, options);
@@ -58,6 +58,7 @@ async function fetchResolvedPropertyList(ref, options) {
   let cacheValidUntil;
   let missingCacheValidUntil = false;
   let cursor;
+  const seenCursors = /* @__PURE__ */ new Set();
   for (let pageIndex = 0; pageIndex < maxPagesForOptions(options); pageIndex += 1) {
     const args = buildResolveListArgs(ref.list_id, pageSizeForOptions(options), cursor);
     const raw = await callTool(ref.agent_url, "get_property_list", args, ref.auth_token);
@@ -65,6 +66,20 @@ async function fetchResolvedPropertyList(ref, options) {
       throw new Error("property_list_invalid_response");
     }
     const response = raw;
+    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)) {
+      throw new Error("property_list_invalid_response");
+    }
+    if (options.strictResponseValidation) {
+      const { GetPropertyListResponseSchema } = await import("../types/schemas.generated.mjs");
+      if (!GetPropertyListResponseSchema.safeParse(raw).success || response.status !== "completed" || response.identifiers.length > pageSizeForOptions(options)) {
+        throw new Error("property_list_invalid_response");
+      }
+    }
+    if (!response.list || response.list.list_id !== ref.list_id || response.identifiers !== void 0 && (!Array.isArray(response.identifiers) || response.identifiers.some(
+      (identifier) => !identifier || typeof identifier !== "object" || typeof identifier.type !== "string" || typeof identifier.value !== "string"
+    ))) {
+      throw new Error("property_list_invalid_response");
+    }
     listId = response.list.list_id;
     identifiers.push(...response.identifiers ?? []);
     if (typeof response.cache_valid_until === "string") {
@@ -87,6 +102,8 @@ async function fetchResolvedPropertyList(ref, options) {
     if (!pagination.cursor) {
       throw new Error("property_list_invalid_pagination");
     }
+    if (seenCursors.has(pagination.cursor)) throw new Error("property_list_invalid_pagination");
+    seenCursors.add(pagination.cursor);
     cursor = pagination.cursor;
   }
   throw new Error("property_list_pagination_limit_exceeded");