@adcp/sdk 8.1.0-beta.13 → 8.1.0-beta.14

package/dist/lib/types/comply-test-controller.d.ts

@@ -183,6 +183,29 @@ export interface ComplyTestControllerRequest {
          */
         upstream_name?: string;
         result?: AdCPAsyncResponseData;
+        /**
+         * ISO 8601 timestamp; only return calls recorded at or after this time. Default: session start. Used by storyboard runners to scope upstream_traffic assertions to a specific step's window.
+         * @format date-time
+         */
+        since_timestamp?: string;
+        /**
+         * Optional server-side filter; reduces response size. Wildcard pattern matched against `<METHOD> <URL>`, e.g. 'POST * /audience/upload' or 'POST *'. When omitted, all recorded calls in the window are returned. **Grammar (normative):** `*` matches zero or more characters of any kind including `/`. No other characters have wildcard semantics — `?` is a literal question mark, `[` and `]` are literal brackets, etc. There is no escape mechanism — `*` is always a wildcard; if literal-asterisk matching is required, callers omit `endpoint_pattern` and filter response-side. Implementations MUST anchor the pattern (full-string match, not substring search). This narrow grammar is intentional — `endpoint_pattern` exists to discriminate platform endpoints (e.g., `POST * /audience/upload` vs `POST * /events/log`), not to express full path-segment grammars. Cross-runner determinism depends on this pinning: a runner that ships POSIX-glob semantics (`*` per-segment, `?` single-char-any) would grade the same storyboard differently than a runner picking the more permissive single-wildcard reading.
+         */
+        endpoint_pattern?: string;
+        /**
+         * Maximum number of calls to return. The response carries `total_count` and `truncated` so the runner can detect overflow.
+         * @minimum 1
+         * @maximum 1000
+         */
+        limit?: number;
+        /**
+         * Requested response shape per recorded call. `raw` (default) returns full payload — the load-bearing assertion target for arbitrary `payload_must_contain` paths, and the existing v2.0.0 contract. `digest` returns only `payload_digest_sha256` + `payload_length` + `content_type` + optional `identifier_match_proofs[]`, so privacy-conscious adopters can support `upstream_traffic` conformance without raw-payload disclosure. Whether digest mode satisfies a given adopter's data-handling obligations (GDPR processor responsibilities, internal data-classification policy, contractual restrictions) is for that adopter's counsel to determine — the spec doesn't promise digest mode clears any specific legal bar. Synthetic-vectors-only still applies (see UpstreamTrafficSuccess top-level description in comply-test-controller-response.json): digest mode reduces what the runner sees, but the controller must still operate on synthetic test data, not production traffic — running queries against production payloads would let a runner with a precomputed digest set learn membership of arbitrary identifiers in the adopter's user base. Adopters MAY unilaterally downgrade a `raw` request to `digest` when their policy requires it; the response's per-call `attestation_mode` field echoes what was actually returned. Storyboards that strictly require raw introspection set `attestation_mode_required: "raw"` on their `upstream_traffic` check — calls returned in digest mode then grade not_applicable rather than failing.
+         */
+        attestation_mode?: 'raw' | 'digest';
+        /**
+         * When `attestation_mode` is `digest`, the runner MAY supply SHA-256 digests (lowercase hex, 64 chars) of identifier values it wants the controller to verify echo for. The controller scans each recorded call's payload for string tokens whose SHA-256 hash matches any digest in this list and returns booleans in `recorded_calls[].identifier_match_proofs[]`. Lets the runner verify `identifier_paths` echo without ever transmitting plaintext identifiers to the controller — the digest is the comparison key. Cap of 64 digests per query to bound the controller's work; storyboards with more identifiers SHOULD batch across multiple queries. Has no effect when `attestation_mode` is `raw` (the runner does the matching in-process against the full payload).
+         */
+        identifier_value_digests?: string[];
     };
     context?: ContextObject;
     ext?: ExtensionObject;
@@ -4027,7 +4050,70 @@ export interface DiagnosticIssue {
  * attestation_mode digest — payload_digest_sha256 required, payload absent. identifier_match_proofs present when the request supplied identifier_value_digests.
  */
 export interface DigestAttestation {
+    /**
+     * HTTP method of the outbound call.
+     */
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+    /**
+     * Composed `<METHOD> <URL>` string used for `endpoint_pattern` matching, e.g. 'POST https://api.tiktok.com/v2/audience/upload'. Convenience field — the runner can also reconstruct from `method` + URL components.
+     */
+    endpoint: string;
+    /**
+     * Full URL of the outbound call (scheme + host + path + query). Treated as untrusted agent-controlled input by report renderers — see runner-output-contract.yaml > security.rendered_output_fencing.
+     */
+    url: string;
+    /**
+     * Host portion of the URL, useful for grouping calls by upstream platform.
+     */
+    host?: string;
+    /**
+     * Path portion of the URL (without query string).
+     */
+    path?: string;
+    /**
+     * Media type of the outbound request body, mirroring the agent's outbound `Content-Type` header (e.g., `application/json`, `application/x-www-form-urlencoded`, `multipart/form-data`, `text/plain`). In raw mode this describes the returned `payload`; in digest mode it describes the body the digest was computed over. Storyboard `payload_must_contain` JSONPath assertions are valid only when content_type is `application/json` or has a `+json` suffix AND attestation_mode is `raw` — digest mode and non-JSON content types grade `payload_must_contain` as not_applicable. Required so the runner can choose the right matcher deterministically.
+     */
+    content_type: string;
     attestation_mode: 'digest';
+    /**
+     * Optional adopter-supplied semantic tag for the call's role. Values: `platform_primary` for the primary upstream platform the adapter is integrating with (e.g., a TikTok audience-upload call from a sales-social adapter); `measurement` for ancillary calls to measurement vendors (DV, IAS, Nielsen, MOAT); `attribution` for server-side conversion APIs (TTD Trans-API, Meta CAPI, AppsFlyer/Branch postbacks) that flow alongside primary platform calls in a buy-step; `creative_serving` for ad-server / CDN / tag-build calls (GAM tag generation, VAST/CDN fetches, creative trafficking); `identity` for ID-graph / hashing-service calls (LiveRamp, ID5, UID2); `other` for everything else (config fetches, internal telemetry, consent signal exchange). Lets storyboards scope `upstream_traffic` assertions via `purpose_filter` so a buyer-agent adapter that legitimately calls measurement vendors during a single buy step doesn't muddy the platform-primary assertion. Calls without a `purpose` field are treated as `purpose: other` for `purpose_filter` matching — adopters who haven't classified are matched only by storyboards filtering on `other` (or by storyboards with no `purpose_filter`). Self-reported, not adversarially trustworthy — same trust model as the rest of recorded_calls; misclassification by a façade is bounded by the runner's reporting of unclassified-call counts in `actual` when filters match zero.
+     */
+    purpose?: 'platform_primary' | 'measurement' | 'attribution' | 'creative_serving' | 'identity' | 'other';
+    /**
+     * SHA-256 digest of the canonicalized outbound request body, lowercase hex (64 chars). Required when `attestation_mode` is `digest`; MUST be absent when `attestation_mode` is `raw`. Canonicalization order is normative: (1) controllers MUST apply the recursive secret-key redaction (same pattern as the raw-mode payload field) BEFORE computing the digest; (2) for `application/json` and `*+json` content types, controllers MUST then serialize the redacted body to RFC 8785 (JCS) canonical form — sorted keys, no extraneous whitespace — and digest the resulting bytes. Storyboard-supplied identifiers (hashed PII, request correlation values) MUST NOT be redacted before digest computation; they are the load-bearing match target for `identifier_match_proofs` and digesting them away makes echo verification impossible. Both `payload_digest_sha256` AND `identifier_match_proofs` MUST be computed against the same post-redaction canonical bytes — diverging the two surfaces breaks coherence between digest replay and identifier echo. JCS edge cases: payloads containing `NaN` or `Infinity` numbers MUST grade `not_applicable` for digest mode (RFC 8785 forbids them); payloads carrying numeric identifiers MUST serialize them as JSON strings before digest computation (adtech bid payloads regularly carry IDs outside ±2^53 where I-JSON / RFC 7493 number round-tripping diverges across implementations). For non-JSON content types the digest is computed over the post-redaction raw body bytes.
+     * @pattern ^[a-f0-9]{64}$
+     */
+    payload_digest_sha256: string;
+    /**
+     * Byte length of the post-redaction canonicalized body. Required in both `raw` and `digest` modes — symmetric across modes so runners can detect adopter-side truncation regardless of attestation choice. In raw mode this MUST equal the byte length of the `payload` value as serialized for transmission; in digest mode this is the length of the canonicalized body the digest covers. Mismatch between observed payload length and reported `payload_length` is a controller-side bug worth surfacing in the report.
+     * @minimum 0
+     */
+    payload_length: number;
+    /**
+     * Per-identifier echo proofs for digest-mode calls. Required when `attestation_mode` is `digest` AND the request supplied `params.identifier_value_digests`; MUST be absent or empty otherwise. Each entry corresponds to one digest from the request. Capped at 64 to match the request-side `params.identifier_value_digests` cap. Lets storyboards verify `identifier_paths` echo in digest mode without ever transmitting plaintext identifiers to the controller. SHA-256 is a privacy mechanism here, not a trust mechanism — controllers self-report `found` and a determined façade can return any boolean; consumers MUST NOT treat digest-mode passing as cryptographically more trustworthy than raw mode. Tokenization is normative: for `application/json` and `*+json` content types, controllers MUST scan exactly the JSON string-typed leaf values of the post-redaction canonicalized body — no substring matching, no word splitting, no case folding, no Unicode normalization. A token matches when its SHA-256 hash equals one of the requested digests byte-for-byte. For non-JSON content types (form-urlencoded, multipart, plain text), `identifier_match_proofs` MUST be empty and runner-side `identifier_paths` assertions targeting those calls grade `not_applicable` — token boundaries are not portably defined across non-JSON shapes.
+     */
+    identifier_match_proofs?: {
+        /**
+         * Echo of one digest from `params.identifier_value_digests` so the runner can pair this proof with the identifier it queried.
+         * @pattern ^[a-f0-9]{64}$
+         */
+        identifier_value_sha256: string;
+        /**
+         * True if any string token in the recorded payload hashes to the queried digest. False otherwise.
+         */
+        found: boolean;
+    }[];
+    /**
+     * ISO 8601 timestamp the adopter recorded the outbound call. MUST reflect the adopter's wall clock at the moment the outbound request was sent (not log-flush time), and MUST be monotonically non-decreasing across recorded_calls of a single response. Used by runners to scope assertions to a specific storyboard step's window — see runner-output-contract.yaml > validation_result for the timestamp boundary semantics.
+     * @format date-time
+     */
+    timestamp: string;
+    /**
+     * HTTP status code returned by the upstream. Optional — adopters MAY omit when the call was instrumented before the response arrived.
+     * @minimum 100
+     * @maximum 599
+     */
+    status_code?: number;
 }
 
 /**
@@ -4050,6 +4136,11 @@ export interface DisplayTagFormatDeclaration {
     params: CanonicalFormatDisplayTag;
 }
 
+/**
+ * Distance unit
+ */
+export type DistanceUnit = 'km' | 'mi' | 'm';
+
 /**
  * DOOH inventory allocation parameters. Sponsorship and takeover flat_rate options omit this field entirely — only include for digital out-of-home inventory.
  */
@@ -7218,7 +7309,57 @@ export interface PushNotificationConfig {
  * attestation_mode raw — payload is required; payload_digest_sha256 and identifier_match_proofs are absent. attestation_mode is required at the item level so the discriminator always has a value to dispatch on (no implicit defaults inside oneOf branches).
  */
 export interface RawAttestation {
+    /**
+     * HTTP method of the outbound call.
+     */
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+    /**
+     * Composed `<METHOD> <URL>` string used for `endpoint_pattern` matching, e.g. 'POST https://api.tiktok.com/v2/audience/upload'. Convenience field — the runner can also reconstruct from `method` + URL components.
+     */
+    endpoint: string;
+    /**
+     * Full URL of the outbound call (scheme + host + path + query). Treated as untrusted agent-controlled input by report renderers — see runner-output-contract.yaml > security.rendered_output_fencing.
+     */
+    url: string;
+    /**
+     * Host portion of the URL, useful for grouping calls by upstream platform.
+     */
+    host?: string;
+    /**
+     * Path portion of the URL (without query string).
+     */
+    path?: string;
+    /**
+     * Media type of the outbound request body, mirroring the agent's outbound `Content-Type` header (e.g., `application/json`, `application/x-www-form-urlencoded`, `multipart/form-data`, `text/plain`). In raw mode this describes the returned `payload`; in digest mode it describes the body the digest was computed over. Storyboard `payload_must_contain` JSONPath assertions are valid only when content_type is `application/json` or has a `+json` suffix AND attestation_mode is `raw` — digest mode and non-JSON content types grade `payload_must_contain` as not_applicable. Required so the runner can choose the right matcher deterministically.
+     */
+    content_type: string;
     attestation_mode: 'raw';
+    /**
+     * Optional adopter-supplied semantic tag for the call's role. Values: `platform_primary` for the primary upstream platform the adapter is integrating with (e.g., a TikTok audience-upload call from a sales-social adapter); `measurement` for ancillary calls to measurement vendors (DV, IAS, Nielsen, MOAT); `attribution` for server-side conversion APIs (TTD Trans-API, Meta CAPI, AppsFlyer/Branch postbacks) that flow alongside primary platform calls in a buy-step; `creative_serving` for ad-server / CDN / tag-build calls (GAM tag generation, VAST/CDN fetches, creative trafficking); `identity` for ID-graph / hashing-service calls (LiveRamp, ID5, UID2); `other` for everything else (config fetches, internal telemetry, consent signal exchange). Lets storyboards scope `upstream_traffic` assertions via `purpose_filter` so a buyer-agent adapter that legitimately calls measurement vendors during a single buy step doesn't muddy the platform-primary assertion. Calls without a `purpose` field are treated as `purpose: other` for `purpose_filter` matching — adopters who haven't classified are matched only by storyboards filtering on `other` (or by storyboards with no `purpose_filter`). Self-reported, not adversarially trustworthy — same trust model as the rest of recorded_calls; misclassification by a façade is bounded by the runner's reporting of unclassified-call counts in `actual` when filters match zero.
+     */
+    purpose?: 'platform_primary' | 'measurement' | 'attribution' | 'creative_serving' | 'identity' | 'other';
+    /**
+     * Request body the agent sent. Required when `attestation_mode` is `raw` (or omitted); MUST be absent when `attestation_mode` is `digest`. Object when content_type is JSON-shaped and the controller decoded it; string otherwise. Adopters MUST apply the recursive secret-key redaction described in this branch's top-level description before emission — secrets at any depth (Authorization values inlined into JSON bodies, embedded JWTs, presigned-URL tokens, OAuth refresh tokens) MUST be replaced with the literal string `[redacted]`. Storyboards that assert `payload_must_contain` or `identifier_paths` are matching against THIS field — secrets MUST be redacted but storyboard-supplied identifiers (hashed PII, request correlation values) MUST NOT be redacted. Adopters SHOULD cap individual payload size at 64 KiB; payloads exceeding that SHOULD be truncated with a trailing `[…truncated]` marker — large payloads bloat compliance reports and the LLM-rendered context windows that consume them.
+     */
+    payload: {
+        [k: string]: unknown | undefined;
+    };
+    /**
+     * Byte length of the post-redaction canonicalized body. Required in both `raw` and `digest` modes — symmetric across modes so runners can detect adopter-side truncation regardless of attestation choice. In raw mode this MUST equal the byte length of the `payload` value as serialized for transmission; in digest mode this is the length of the canonicalized body the digest covers. Mismatch between observed payload length and reported `payload_length` is a controller-side bug worth surfacing in the report.
+     * @minimum 0
+     */
+    payload_length: number;
+    /**
+     * ISO 8601 timestamp the adopter recorded the outbound call. MUST reflect the adopter's wall clock at the moment the outbound request was sent (not log-flush time), and MUST be monotonically non-decreasing across recorded_calls of a single response. Used by runners to scope assertions to a specific storyboard step's window — see runner-output-contract.yaml > validation_result for the timestamp boundary semantics.
+     * @format date-time
+     */
+    timestamp: string;
+    /**
+     * HTTP status code returned by the upstream. Optional — adopters MAY omit when the call was instrumented before the response arrived.
+     * @minimum 100
+     * @maximum 599
+     */
+    status_code?: number;
 }
 
 /**
@@ -8396,9 +8537,98 @@ export interface TargetingOverlay {
     /**
      * Target users within travel time, distance, or a custom boundary around arbitrary geographic points. Multiple entries use OR semantics — a user within range of any listed point is eligible. For campaigns targeting 10+ locations, consider using store_catchments with a location catalog instead. Seller must declare support in get_adcp_capabilities.
      */
-    geo_proximity?: {
-        [k: string]: unknown | undefined;
-    }[];
+    geo_proximity?: ({
+        /**
+         * Latitude in decimal degrees (WGS 84). Required for travel_time and radius methods.
+         * @minimum -90
+         * @maximum 90
+         */
+        lat: number;
+        /**
+         * Longitude in decimal degrees (WGS 84). Required for travel_time and radius methods.
+         * @minimum -180
+         * @maximum 180
+         */
+        lng: number;
+        /**
+         * Human-readable label for this entry (e.g., 'Düsseldorf', 'Heathrow Airport', 'Primary trade area').
+         */
+        label?: string;
+        /**
+         * Travel time limit for isochrone calculation. The platform resolves this to a geographic boundary based on actual transportation networks.
+         */
+        travel_time: {
+            /**
+             * Travel time limit.
+             * @minimum 1
+             */
+            value: number;
+            unit: TravelTimeUnit;
+        };
+        transport_mode: TransportMode;
+        ext?: ExtensionObject;
+    } | {
+        /**
+         * Latitude in decimal degrees (WGS 84). Required for travel_time and radius methods.
+         * @minimum -90
+         * @maximum 90
+         */
+        lat: number;
+        /**
+         * Longitude in decimal degrees (WGS 84). Required for travel_time and radius methods.
+         * @minimum -180
+         * @maximum 180
+         */
+        lng: number;
+        /**
+         * Human-readable label for this entry (e.g., 'Düsseldorf', 'Heathrow Airport', 'Primary trade area').
+         */
+        label?: string;
+        transport_mode?: TransportMode;
+        /**
+         * Simple radius from the point. The platform draws a circle of this distance around the coordinates.
+         */
+        radius: {
+            /**
+             * Radius distance.
+             */
+            value: number;
+            unit: DistanceUnit;
+        };
+        ext?: ExtensionObject;
+    } | {
+        /**
+         * Latitude in decimal degrees (WGS 84). Required for travel_time and radius methods.
+         * @minimum -90
+         * @maximum 90
+         */
+        lat?: number;
+        /**
+         * Longitude in decimal degrees (WGS 84). Required for travel_time and radius methods.
+         * @minimum -180
+         * @maximum 180
+         */
+        lng?: number;
+        /**
+         * Human-readable label for this entry (e.g., 'Düsseldorf', 'Heathrow Airport', 'Primary trade area').
+         */
+        label?: string;
+        transport_mode?: TransportMode;
+        /**
+         * Pre-computed GeoJSON geometry defining the proximity boundary. Use when the buyer has already calculated isochrones (via TravelTime, Mapbox, etc.) or has custom boundaries. When geometry is provided, lat/lng are not required.
+         */
+        geometry: {
+            /**
+             * GeoJSON geometry type.
+             */
+            type: 'Polygon' | 'MultiPolygon';
+            /**
+             * GeoJSON coordinates array. For Polygon: array of linear rings. For MultiPolygon: array of polygons.
+             */
+            coordinates: unknown[];
+        };
+        ext?: ExtensionObject;
+    })[];
     /**
      * Restrict to users with specific language preferences. ISO 639-1 codes (e.g., 'en', 'es', 'fr').
      */
@@ -8520,6 +8750,16 @@ export interface TimeBasedPricingOption {
     eligible_adjustments?: PriceAdjustmentKind[];
 }
 
+/**
+ * Transportation mode for isochrone calculation. Required when travel_time is provided.
+ */
+export type TransportMode = 'walking' | 'cycling' | 'driving' | 'public_transport';
+
+/**
+ * Time unit for isochrone (travel-time catchment) calculations.
+ */
+export type TravelTimeUnit = 'min' | 'hr';
+
 /**
  * Type of user identifier. Used in audience sync, event logging, and TMP identity match requests to tell the receiver which identity graph to resolve against.
  */

package/dist/lib/types/core.generated.d.ts

@@ -156,6 +156,18 @@ export type DevicePlatform = 'ios' | 'android' | 'windows' | 'macos' | 'linux' |
  * Device form factor categories for targeting and reporting. Complements device-platform (operating system) with hardware classification. OpenRTB mapping: 1 (Mobile/Tablet General) → mobile, 2 (PC) → desktop, 4 (Phone) → mobile, 5 (Tablet) → tablet, 6 (Connected Device) → ctv, 7 (Set Top Box) → ctv. DOOH inventory uses dooh.
  */
 export type DeviceType = 'desktop' | 'mobile' | 'tablet' | 'ctv' | 'dooh' | 'unknown';
+/**
+ * Time unit for isochrone (travel-time catchment) calculations.
+ */
+export type TravelTimeUnit = 'min' | 'hr';
+/**
+ * Transportation mode for isochrone calculation. Required when travel_time is provided.
+ */
+export type TransportMode = 'walking' | 'cycling' | 'driving' | 'public_transport';
+/**
+ * Distance unit.
+ */
+export type DistanceUnit = 'km' | 'mi' | 'm';
 /**
  * Keyword targeting match type. broad: ads may serve on queries semantically related to the keyword. phrase: ads serve when the query contains the keyword phrase. exact: ads serve only when the query matches the keyword exactly.
  */
@@ -1604,9 +1616,98 @@ export interface TargetingOverlay {
     /**
      * Target users within travel time, distance, or a custom boundary around arbitrary geographic points. Multiple entries use OR semantics — a user within range of any listed point is eligible. For campaigns targeting 10+ locations, consider using store_catchments with a location catalog instead. Seller must declare support in get_adcp_capabilities.
      */
-    geo_proximity?: {
-        [k: string]: unknown | undefined;
-    }[];
+    geo_proximity?: ({
+        /**
+         * Latitude in decimal degrees (WGS 84). Required for travel_time and radius methods.
+         * @minimum -90
+         * @maximum 90
+         */
+        lat: number;
+        /**
+         * Longitude in decimal degrees (WGS 84). Required for travel_time and radius methods.
+         * @minimum -180
+         * @maximum 180
+         */
+        lng: number;
+        /**
+         * Human-readable label for this entry (e.g., 'Düsseldorf', 'Heathrow Airport', 'Primary trade area').
+         */
+        label?: string;
+        /**
+         * Travel time limit for isochrone calculation. The platform resolves this to a geographic boundary based on actual transportation networks.
+         */
+        travel_time: {
+            /**
+             * Travel time limit.
+             * @minimum 1
+             */
+            value: number;
+            unit: TravelTimeUnit;
+        };
+        transport_mode: TransportMode;
+        ext?: ExtensionObject;
+    } | {
+        /**
+         * Latitude in decimal degrees (WGS 84). Required for travel_time and radius methods.
+         * @minimum -90
+         * @maximum 90
+         */
+        lat: number;
+        /**
+         * Longitude in decimal degrees (WGS 84). Required for travel_time and radius methods.
+         * @minimum -180
+         * @maximum 180
+         */
+        lng: number;
+        /**
+         * Human-readable label for this entry (e.g., 'Düsseldorf', 'Heathrow Airport', 'Primary trade area').
+         */
+        label?: string;
+        transport_mode?: TransportMode;
+        /**
+         * Simple radius from the point. The platform draws a circle of this distance around the coordinates.
+         */
+        radius: {
+            /**
+             * Radius distance.
+             */
+            value: number;
+            unit: DistanceUnit;
+        };
+        ext?: ExtensionObject;
+    } | {
+        /**
+         * Latitude in decimal degrees (WGS 84). Required for travel_time and radius methods.
+         * @minimum -90
+         * @maximum 90
+         */
+        lat?: number;
+        /**
+         * Longitude in decimal degrees (WGS 84). Required for travel_time and radius methods.
+         * @minimum -180
+         * @maximum 180
+         */
+        lng?: number;
+        /**
+         * Human-readable label for this entry (e.g., 'Düsseldorf', 'Heathrow Airport', 'Primary trade area').
+         */
+        label?: string;
+        transport_mode?: TransportMode;
+        /**
+         * Pre-computed GeoJSON geometry defining the proximity boundary. Use when the buyer has already calculated isochrones (via TravelTime, Mapbox, etc.) or has custom boundaries. When geometry is provided, lat/lng are not required.
+         */
+        geometry: {
+            /**
+             * GeoJSON geometry type.
+             */
+            type: 'Polygon' | 'MultiPolygon';
+            /**
+             * GeoJSON coordinates array. For Polygon: array of linear rings. For MultiPolygon: array of polygons.
+             */
+            coordinates: unknown[];
+        };
+        ext?: ExtensionObject;
+    })[];
     /**
      * Restrict to users with specific language preferences. ISO 639-1 codes (e.g., 'en', 'es', 'fr').
      */
@@ -16518,9 +16619,95 @@ export interface ProductFilters {
     /**
      * Filter by proximity to geographic points. Returns products with inventory coverage near these locations. Follows the same format as the targeting overlay — each entry uses exactly one method: travel_time + transport_mode, radius, or geometry. For locally-bound inventory (DOOH, radio), filters to products with coverage in the area. For digital inventory, filters to products from sellers supporting geo_proximity targeting.
      */
-    geo_proximity?: {
-        [k: string]: unknown | undefined;
-    }[];
+    geo_proximity?: ({
+        /**
+         * Latitude in decimal degrees (WGS 84)
+         * @minimum -90
+         * @maximum 90
+         */
+        lat: number;
+        /**
+         * Longitude in decimal degrees (WGS 84)
+         * @minimum -180
+         * @maximum 180
+         */
+        lng: number;
+        /**
+         * Human-readable label (e.g., 'Düsseldorf', 'Heathrow Airport')
+         */
+        label?: string;
+        /**
+         * Travel time limit for isochrone calculation
+         */
+        travel_time: {
+            /**
+             * Travel time limit
+             * @minimum 1
+             */
+            value: number;
+            unit: TravelTimeUnit;
+        };
+        transport_mode: TransportMode;
+    } | {
+        /**
+         * Latitude in decimal degrees (WGS 84)
+         * @minimum -90
+         * @maximum 90
+         */
+        lat: number;
+        /**
+         * Longitude in decimal degrees (WGS 84)
+         * @minimum -180
+         * @maximum 180
+         */
+        lng: number;
+        /**
+         * Human-readable label (e.g., 'Düsseldorf', 'Heathrow Airport')
+         */
+        label?: string;
+        transport_mode?: TransportMode;
+        /**
+         * Simple radius from the point
+         */
+        radius: {
+            /**
+             * Radius distance
+             */
+            value: number;
+            unit: DistanceUnit;
+        };
+    } | {
+        /**
+         * Latitude in decimal degrees (WGS 84)
+         * @minimum -90
+         * @maximum 90
+         */
+        lat?: number;
+        /**
+         * Longitude in decimal degrees (WGS 84)
+         * @minimum -180
+         * @maximum 180
+         */
+        lng?: number;
+        /**
+         * Human-readable label (e.g., 'Düsseldorf', 'Heathrow Airport')
+         */
+        label?: string;
+        transport_mode?: TransportMode;
+        /**
+         * Pre-computed GeoJSON geometry defining the proximity boundary
+         */
+        geometry: {
+            /**
+             * GeoJSON geometry type
+             */
+            type: 'Polygon' | 'MultiPolygon';
+            /**
+             * GeoJSON coordinates array
+             */
+            coordinates: unknown[];
+        };
+    })[];
     /**
      * Filter to products that can meet the buyer's performance standard requirements. Each entry specifies a metric, minimum threshold, and optionally a required vendor and standard. Products that cannot meet these thresholds or do not support the specified vendors are excluded. Use this to tell the seller upfront: 'I need DoubleVerify for viewability at 70% MRC.'
      */
@@ -19326,10 +19513,6 @@ export type GetAdCPCapabilitiesResponse = ProtocolEnvelope & {
         event_types?: ('product.created' | 'product.updated' | 'product.priced' | 'product.removed' | 'signal.created' | 'signal.updated' | 'signal.priced' | 'signal.removed' | 'wholesale_feed.bulk_change')[];
     };
 };
-/**
- * Transportation modes for isochrone-based catchment area calculations. Determines how travel time translates to geographic reach.
- */
-export type TransportMode = 'walking' | 'cycling' | 'driving' | 'public_transport';
 /**
  * Specialized capability claims an agent can make. Each specialism maps to a compliance storyboard bundle published at /compliance/{version}/specialisms/{id}/. An agent asserts specialisms it supports in get_adcp_capabilities; the AAO compliance runner executes the matching storyboards to verify the claim.
  */
@@ -21022,17 +21205,74 @@ export type Catchment = {
         coordinates: unknown[];
     };
     ext?: ExtensionObject;
-} & {
-    [k: string]: unknown | undefined;
-};
-/**
- * Time unit for isochrone (travel-time catchment) calculations.
- */
-export type TravelTimeUnit = 'min' | 'hr';
-/**
- * Distance unit.
- */
-export type DistanceUnit = 'km' | 'mi' | 'm';
+} & ({
+    /**
+     * Identifier for this catchment, used to reference specific catchment areas in targeting (e.g., 'walk', 'drive', 'primary').
+     */
+    catchment_id: string;
+    /**
+     * Human-readable label for this catchment (e.g., '15-min drive', '1km walking radius').
+     */
+    label?: string;
+    /**
+     * Travel time limit for isochrone calculation. The platform resolves this to a geographic boundary based on actual transportation networks, accounting for road connectivity, transit schedules, and terrain.
+     */
+    travel_time: {
+        /**
+         * Travel time limit.
+         * @minimum 1
+         */
+        value: number;
+        unit: TravelTimeUnit;
+    };
+    transport_mode: TransportMode;
+    ext?: ExtensionObject;
+} | {
+    /**
+     * Identifier for this catchment, used to reference specific catchment areas in targeting (e.g., 'walk', 'drive', 'primary').
+     */
+    catchment_id: string;
+    /**
+     * Human-readable label for this catchment (e.g., '15-min drive', '1km walking radius').
+     */
+    label?: string;
+    transport_mode?: TransportMode;
+    /**
+     * Simple radius from the store location. The platform draws a circle of this distance around the store's coordinates.
+     */
+    radius: {
+        /**
+         * Radius distance.
+         */
+        value: number;
+        unit: DistanceUnit;
+    };
+    ext?: ExtensionObject;
+} | {
+    /**
+     * Identifier for this catchment, used to reference specific catchment areas in targeting (e.g., 'walk', 'drive', 'primary').
+     */
+    catchment_id: string;
+    /**
+     * Human-readable label for this catchment (e.g., '15-min drive', '1km walking radius').
+     */
+    label?: string;
+    transport_mode?: TransportMode;
+    /**
+     * Pre-computed GeoJSON geometry defining the catchment boundary. Use this when the buyer has already calculated isochrones (via TravelTime, Mapbox, etc.) or has custom trade area boundaries. Supports Polygon and MultiPolygon types.
+     */
+    geometry: {
+        /**
+         * GeoJSON geometry type.
+         */
+        type: 'Polygon' | 'MultiPolygon';
+        /**
+         * GeoJSON coordinates array. For Polygon: array of linear rings. For MultiPolygon: array of polygons.
+         */
+        coordinates: unknown[];
+    };
+    ext?: ExtensionObject;
+});
 /**
  * A collection's presence on a specific publisher platform, identified by platform-specific identifiers. Enables cross-seller matching when the same collection is sold by different agents.
  */