@adcp/sdk 5.25.0 → 6.0.0

package/dist/lib/server/decisioning/async-outcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-outcome.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/decisioning/async-outcome.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,k8BA8CpB,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AA+B3D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IAChC,QAAQ,EAAE,WAAW,GAAG,aAAa,GAAG,UAAU,CAAC;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAG,WAAW,CAAU;IACrC,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACzC,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,aAAa,GAAG,UAAU,CAAC;IAC5D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAGzC,IAAI,EAAE,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,EAC/B,OAAO,EAAE;QACP,QAAQ,EAAE,WAAW,GAAG,aAAa,GAAG,UAAU,CAAC;QACnD,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC;IAYH,kFAAkF;IAClF,iBAAiB,IAAI,mBAAmB;IAYxC;;;;;;OAMG;IACM,QAAQ,IAAI,MAAM;CAG5B;AAMD;;;;GAIG;AACH,QAAA,MAAM,kBAAkB,EAAE,OAAO,MAAqD,CAAC;AAavF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,WAAW,CAAC,OAAO;IAClC,QAAQ,CAAC,CAAC,kBAAkB,CAAC,EAAE,IAAI,CAAC;CASrC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB"}

package/dist/lib/server/decisioning/async-outcome.js

@@ -0,0 +1,239 @@
+"use strict";
+/**
+ * Error vocabulary + structured error class for `DecisioningPlatform`.
+ *
+ * Adopters write per-tool methods (sync OR `*Task` HITL variant), return
+ * the success value, or `throw new AdcpError(...)` for structured rejection.
+ * The framework projects the structured fields onto the wire `adcp_error`
+ * envelope; generic thrown errors map to `SERVICE_UNAVAILABLE`.
+ *
+ * `AsyncOutcome<T>` and the `ok` / `submitted` / `rejected` constructors
+ * remain as the framework's internal projection vocabulary; adopter code
+ * doesn't return them.
+ *
+ * Status: Preview / 6.0.
+ *
+ * @public
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdcpError = exports.KNOWN_ERROR_CODES = void 0;
+exports._createTaskHandoff = _createTaskHandoff;
+exports.isTaskHandoff = isTaskHandoff;
+exports._extractTaskFn = _extractTaskFn;
+/**
+ * Error code vocabulary mirroring `schemas/cache/3.0.0/enums/error-code.json`
+ * (45 standard codes). Adopters can return platform-specific codes too —
+ * agents fall back to the `recovery` classification on unknowns via the
+ * `(string & {})` escape hatch on `AdcpStructuredError.code`.
+ *
+ * TODO(6.0): generate this from `schemas/cache/<version>/enums/error-code.json`
+ * via the same codegen pipeline as the rest of `tools.generated.ts`.
+ */
+exports.KNOWN_ERROR_CODES = [
+    'INVALID_REQUEST',
+    'AUTH_REQUIRED',
+    'RATE_LIMITED',
+    'SERVICE_UNAVAILABLE',
+    'POLICY_VIOLATION',
+    'PRODUCT_NOT_FOUND',
+    'PRODUCT_UNAVAILABLE',
+    'PRODUCT_EXPIRED',
+    'PROPOSAL_EXPIRED',
+    'PROPOSAL_NOT_COMMITTED',
+    'BUDGET_TOO_LOW',
+    'BUDGET_EXHAUSTED',
+    'BUDGET_EXCEEDED',
+    'CREATIVE_REJECTED',
+    'CREATIVE_DEADLINE_EXCEEDED',
+    'CREATIVE_NOT_FOUND',
+    'UNSUPPORTED_FEATURE',
+    'AUDIENCE_TOO_SMALL',
+    'ACCOUNT_NOT_FOUND',
+    'ACCOUNT_SETUP_REQUIRED',
+    'ACCOUNT_AMBIGUOUS',
+    'ACCOUNT_PAYMENT_REQUIRED',
+    'ACCOUNT_SUSPENDED',
+    'COMPLIANCE_UNSATISFIED',
+    'GOVERNANCE_DENIED',
+    'GOVERNANCE_UNAVAILABLE',
+    'CAMPAIGN_SUSPENDED',
+    'CONFLICT',
+    'IDEMPOTENCY_CONFLICT',
+    'IDEMPOTENCY_EXPIRED',
+    'INVALID_STATE',
+    'IO_REQUIRED',
+    'MEDIA_BUY_NOT_FOUND',
+    'NOT_CANCELLABLE',
+    'PACKAGE_NOT_FOUND',
+    'PERMISSION_DENIED',
+    'PLAN_NOT_FOUND',
+    'REFERENCE_NOT_FOUND',
+    'REQUOTE_REQUIRED',
+    'SESSION_NOT_FOUND',
+    'SESSION_TERMINATED',
+    'SIGNAL_NOT_FOUND',
+    'TERMS_REJECTED',
+    'VALIDATION_ERROR',
+    'VERSION_UNSUPPORTED',
+];
+const KNOWN_ERROR_CODE_SET = new Set(exports.KNOWN_ERROR_CODES);
+/**
+ * Detect typoed error codes in `AdcpError` constructor calls. The
+ * `code: ErrorCode | (string & {})` escape hatch keeps platform-specific
+ * codes available, but it also defeats autocomplete on misspellings —
+ * `'BUDGET_TO_LOW'` (typo) compiles fine. The runtime warns once per
+ * unknown code so `npm run dev` log review surfaces typos before they
+ * ship to a buyer who can't pattern-match `recovery`.
+ *
+ * Set `ADCP_DECISIONING_ALLOW_CUSTOM_CODES=1` to silence the warn for
+ * platforms that intentionally mint vendor-specific codes
+ * (`'GAM_INTERNAL_QUOTA_EXCEEDED'` etc.).
+ */
+const warnedUnknownCodes = new Set();
+function maybeWarnUnknownErrorCode(code) {
+    if (KNOWN_ERROR_CODE_SET.has(code))
+        return;
+    if (process.env.ADCP_DECISIONING_ALLOW_CUSTOM_CODES === '1')
+        return;
+    if (warnedUnknownCodes.has(code))
+        return;
+    warnedUnknownCodes.add(code);
+    // eslint-disable-next-line no-console
+    console.warn(`[adcp/decisioning] AdcpError code "${code}" is not in the known ErrorCode set ` +
+        `(45 standard codes per schemas/cache/3.0.0/enums/error-code.json). ` +
+        `If this is intentional (vendor-specific code), set ADCP_DECISIONING_ALLOW_CUSTOM_CODES=1. ` +
+        `Otherwise check spelling against the ErrorCode union.`);
+}
+/**
+ * Throwable structured error. Adopter code throws this to fail a specialism
+ * method with a buyer-facing wire envelope.
+ *
+ * ```ts
+ * createMediaBuy: async (req, ctx) => {
+ *   if (req.total_budget.amount < this.floor) {
+ *     throw new AdcpError('BUDGET_TOO_LOW', {
+ *       recovery: 'correctable',
+ *       message: `Floor is $${this.floor} CPM`,
+ *       field: 'total_budget.amount',
+ *     });
+ *   }
+ *   return await this.gam.createOrder(req);
+ * }
+ * ```
+ *
+ * Framework catches `AdcpError` from any specialism method and projects
+ * the structured fields onto the wire `adcp_error` envelope.
+ * Generic thrown errors map to `SERVICE_UNAVAILABLE` with `recovery: 'transient'`.
+ */
+class AdcpError extends Error {
+    name = 'AdcpError';
+    code;
+    recovery;
+    field;
+    suggestion;
+    retry_after;
+    details;
+    constructor(code, options) {
+        super(options.message);
+        this.code = code;
+        this.recovery = options.recovery;
+        maybeWarnUnknownErrorCode(code);
+        if (options.field !== undefined)
+            this.field = options.field;
+        if (options.suggestion !== undefined)
+            this.suggestion = options.suggestion;
+        if (options.retry_after !== undefined)
+            this.retry_after = options.retry_after;
+        if (options.details !== undefined)
+            this.details = options.details;
+    }
+    /** Coerce to the structured envelope shape the framework projects to the wire. */
+    toStructuredError() {
+        return {
+            code: this.code,
+            recovery: this.recovery,
+            message: this.message,
+            ...(this.field !== undefined && { field: this.field }),
+            ...(this.suggestion !== undefined && { suggestion: this.suggestion }),
+            ...(this.retry_after !== undefined && { retry_after: this.retry_after }),
+            ...(this.details !== undefined && { details: this.details }),
+        };
+    }
+    /**
+     * Override `Error.toString` so default `console.error(err)` /
+     * CloudWatch / structured-log adopters see the `code` and `recovery`
+     * alongside the message rather than the bare `AdcpError: <message>`
+     * default. Triage in operator dashboards needs the code more than
+     * the stack.
+     */
+    toString() {
+        return `AdcpError [${this.code}, ${this.recovery}]: ${this.message}`;
+    }
+}
+exports.AdcpError = AdcpError;
+// ---------------------------------------------------------------------------
+// TaskHandoff — unified hybrid-seller shape
+// ---------------------------------------------------------------------------
+/**
+ * Brand value framework checks at the dispatch seam to detect "this method
+ * is handing off to a task." Module-level constant so adopters can't construct
+ * one without going through `ctx.handoffToTask(fn)`.
+ */
+const TASK_HANDOFF_BRAND = Symbol.for('@adcp/decisioning/task-handoff');
+/**
+ * The handoff function lives in a WeakMap keyed by the `TaskHandoff`
+ * marker object — NOT on the marker itself. This means the framework
+ * can extract the function (it has the WeakMap reference) but adopters
+ * holding only a `TaskHandoff<T>` value cannot invoke or inspect it.
+ * Closes round-6 CR-3 / Protocol-L2: `_taskFn` was previously a
+ * type-visible field that adopters could forge with their own
+ * `Symbol.for(...)` call.
+ */
+const taskHandoffFns = new WeakMap();
+/**
+ * Construct a `TaskHandoff<T>` marker. The framework's `ctx.handoffToTask`
+ * helper invokes this; adopters don't call it directly.
+ *
+ * The `fn` is stashed in a module-private WeakMap keyed by the marker
+ * object. Adopters can hold the marker and pass it through return
+ * values, but cannot extract or invoke `fn` themselves — only the
+ * framework's `_extractTaskFn` can.
+ *
+ * @internal
+ */
+function _createTaskHandoff(fn) {
+    // Frozen object so adopters can't mutate the brand field. Even if
+    // they did, the dispatch seam keys on identity (WeakMap), not on
+    // mutable structure.
+    const marker = Object.freeze({ [TASK_HANDOFF_BRAND]: true });
+    taskHandoffFns.set(marker, fn);
+    return marker;
+}
+/**
+ * Type guard — does the value the adopter returned mark a task handoff?
+ *
+ * Checks both the symbol brand AND WeakMap presence. An adopter who
+ * forges `{ [TASK_HANDOFF_BRAND]: true }` without going through
+ * `_createTaskHandoff` won't be in the WeakMap and the guard returns
+ * false. Belt-and-suspenders against forgery.
+ *
+ * @internal
+ */
+function isTaskHandoff(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[TASK_HANDOFF_BRAND] === true &&
+        taskHandoffFns.has(value));
+}
+/**
+ * Extract the handoff function from a marker. Framework-only — the
+ * dispatch seam in `from-platform.ts` calls this after `isTaskHandoff`.
+ * Returns `undefined` if the marker wasn't created by `_createTaskHandoff`
+ * (forgery).
+ *
+ * @internal
+ */
+function _extractTaskFn(handoff) {
+    return taskHandoffFns.get(handoff);
+}
+//# sourceMappingURL=async-outcome.js.map

package/dist/lib/server/decisioning/async-outcome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-outcome.js","sourceRoot":"","sources":["../../../../src/lib/server/decisioning/async-outcome.ts"],"names":[],"mappings":"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"}

package/dist/lib/server/decisioning/capabilities.d.ts

@@ -0,0 +1,251 @@
+/**
+ * DecisioningCapabilities — single source of truth for `get_adcp_capabilities`
+ * response and any admin UI surface a host wants to render.
+ *
+ * Adopters declare once. Framework wires the wire-protocol response;
+ * adopters' admin tools (or the SDK CLI's `validate_platform_config`) consume
+ * the same dataclass so there's no drift between "what the agent says it
+ * supports" and "what it actually does."
+ *
+ * Status: Preview / 6.0.
+ *
+ * @public
+ */
+import type { ZodSchema } from 'zod';
+import type { AdCPSpecialism, MediaChannel, PricingModel, GetAdCPCapabilitiesResponse } from '../../types/tools.generated';
+export interface DecisioningCapabilities<TConfig = unknown> {
+    /**
+     * Specialisms claimed; framework type-checks these against implemented platform
+     * interfaces. Arrays are `readonly` so adopters can declare with `as const`
+     * (load-bearing for the `RequiredPlatformsFor<S>` compile-time gate).
+     */
+    specialisms: readonly AdCPSpecialism[];
+    /**
+     * Creative agents this seller composes with. Framework fetches format catalogs
+     * from each (1h cache) and unions them on `list_creative_formats`. Self-hosting
+     * sellers point at their own `agent_url`; framework calls into their
+     * `CreativePlatform.listFormats()` locally instead of HTTP-fetching.
+     *
+     * `format_ids` filter (optional) subsets a single creative agent's catalog.
+     * Useful when a creative agent hosts 50 formats but this seller only accepts
+     * 10 of them. Filter scope is per-creative-agent: `[{ agent_url: A, format_ids: ['x'] }, { agent_url: B }]`
+     * means "from A only format x; from B all formats."
+     */
+    creative_agents: readonly CreativeAgentRef[];
+    /** Channels this platform sells. */
+    channels: readonly MediaChannel[];
+    /** Pricing models this platform supports. */
+    pricingModels: readonly PricingModel[];
+    /** Targeting capabilities. Optional — framework infers reasonable defaults if omitted. */
+    targeting?: TargetingCapabilities;
+    /** Reporting capabilities. Optional — framework infers reasonable defaults if omitted. */
+    reporting?: ReportingCapabilities;
+    /**
+     * Audience-matching capabilities — projected onto
+     * `get_adcp_capabilities.media_buy.audience_targeting`. Required for
+     * audience-sync adopters (CRM-list adopters that accept hashed
+     * identifiers + UID types) so buyers know which identifier shapes
+     * the platform will match against and what minimum audience size /
+     * matching latency to expect. Omit when the platform doesn't accept
+     * external audience uploads.
+     *
+     * Wire spec: `core/get-adcp-capabilities-response.json#media_buy.audience_targeting`.
+     */
+    audience_targeting?: NonNullable<NonNullable<GetAdCPCapabilitiesResponse['media_buy']>['audience_targeting']>;
+    /**
+     * Conversion-tracking capabilities — projected onto
+     * `get_adcp_capabilities.media_buy.conversion_tracking`. Required for
+     * adopters that accept conversion events via `sync_event_sources` /
+     * `log_event` so buyers know which event types, action sources,
+     * attribution windows, and identifier shapes the platform supports.
+     * Omit when the platform doesn't track conversions.
+     *
+     * Wire spec: `core/get-adcp-capabilities-response.json#media_buy.conversion_tracking`.
+     */
+    conversion_tracking?: NonNullable<NonNullable<GetAdCPCapabilitiesResponse['media_buy']>['conversion_tracking']>;
+    /**
+     * Content-standards capabilities — projected onto
+     * `get_adcp_capabilities.media_buy.content_standards`. Required for
+     * adopters claiming the `content-standards` specialism so buyers know
+     * whether the platform runs local evaluation, which channels it
+     * covers, and whether it supports webhook artifact delivery. Omit
+     * when the platform doesn't ship content-standards artifacts.
+     *
+     * Wire spec: `core/get-adcp-capabilities-response.json#media_buy.content_standards`.
+     */
+    content_standards?: NonNullable<NonNullable<GetAdCPCapabilitiesResponse['media_buy']>['content_standards']>;
+    /**
+     * Brand-protocol capabilities. Projected onto the wire `brand` block of
+     * `get_adcp_capabilities` (`brand: { rights, right_types, available_uses,
+     * generation_providers, description }`). The framework auto-derives
+     * `rights: true` when `BrandRightsPlatform` is supplied; adopters
+     * declare the rest (right_types they license, RightUses they support,
+     * generation providers they issue credentials for).
+     *
+     * REQUIRED when claiming the `'brand-rights'` specialism — enforced at
+     * compile-time via `RequiredCapabilitiesFor<S>`.
+     */
+    brand?: BrandCapabilities;
+    /**
+     * Compliance-testing capabilities. The presence of this block declares
+     * the agent supports deterministic state-machine testing via the
+     * `comply_test_controller` wire tool. Omit entirely if the agent
+     * doesn't support compliance testing.
+     *
+     * When this block is present, `createAdcpServerFromPlatform` REQUIRES
+     * `opts.complyTest` (the `ComplyControllerConfig` adapter set) to be
+     * supplied — claiming the capability without implementing the
+     * controller is a `PlatformConfigError` at construction.
+     *
+     * Inversely, supplying `opts.complyTest` without declaring this
+     * capability is also caught — the framework derives `scenarios` from
+     * the declared force/simulate/seed adapters and emits the discovery
+     * field on `get_adcp_capabilities` automatically. Adopters who want
+     * to explicitly declare a narrower or wider scenarios list can supply
+     * this block; otherwise the auto-derivation wins.
+     */
+    compliance_testing?: ComplianceTestingCapabilities;
+    /**
+     * Billing parties this platform supports. `'operator'` = retail-media model
+     * (Criteo, Amazon — operator pays the publisher and bills the brand).
+     * `'agent'` = pass-through model (buyer's agent settles directly with the
+     * platform). Defaults to `['agent']` when omitted.
+     */
+    supportedBillings?: ReadonlyArray<'operator' | 'agent'>;
+    /**
+     * If true, this platform refuses transactions without an authenticated
+     * operator principal (operator-billed retail-media). Framework emits
+     * `AUTH_REQUIRED` envelope before dispatching to the platform.
+     */
+    requireOperatorAuth?: boolean;
+    /**
+     * Platform-specific config. Strongly typed when the adopter uses the generic.
+     * Example: `class GAM extends DecisioningPlatform<{ networkId: string }>`.
+     */
+    config: TConfig;
+    /**
+     * Optional Zod schema for runtime validation of `config`. When provided,
+     * framework validates at platform construction time; missing or wrong-shaped
+     * config rejects the agent at boot rather than at first request.
+     */
+    configSchema?: ZodSchema<TConfig>;
+}
+export interface CreativeAgentRef {
+    agent_url: string;
+    /** Human-readable label for this creative agent. */
+    name?: string;
+    /** Optional allowlist of `format_id.id` values from THIS agent's catalog. Omit to include all. */
+    format_ids?: string[];
+}
+/**
+ * Targeting capabilities the platform supports in `create_media_buy`. Maps
+ * to AdCP `GetAdcpCapabilitiesResponse.media_buy.execution.targeting`.
+ *
+ * Shape converged across two independently-evolved peer codebases (Scope3
+ * `agentic-adapters`, Prebid `salesagent`). Per-geo-system flags rather than
+ * coarse enums because the two implementations agreed: real platforms support
+ * specific geo identifier formats (Nielsen DMA, Eurostat NUTS2, US ZIP+4), not
+ * abstract "metro" / "postal" categories.
+ */
+export interface TargetingCapabilities {
+    geo_countries?: boolean;
+    geo_regions?: boolean;
+    /** Metro / DMA identifier systems. */
+    geo_metros?: {
+        nielsen_dma?: boolean;
+        uk_itl1?: boolean;
+        uk_itl2?: boolean;
+        eurostat_nuts2?: boolean;
+    };
+    /** Postal-code identifier systems. */
+    geo_postal_areas?: {
+        us_zip?: boolean;
+        us_zip_plus_four?: boolean;
+        gb_outward?: boolean;
+        gb_full?: boolean;
+        ca_fsa?: boolean;
+        ca_full?: boolean;
+        de_plz?: boolean;
+        fr_code_postal?: boolean;
+        au_postcode?: boolean;
+        ch_plz?: boolean;
+        at_plz?: boolean;
+    };
+    /** Geographic-proximity targeting (radius / drive-time / arbitrary geometry). */
+    geo_proximity?: {
+        radius?: boolean;
+        travel_time?: boolean;
+        geometry?: boolean;
+        transport_modes?: ReadonlyArray<'walking' | 'cycling' | 'driving' | 'public_transport'>;
+    };
+    /** Age-restriction targeting; `verification_methods` enumerates the assurance levels accepted. */
+    age_restriction?: {
+        supported?: boolean;
+        verification_methods?: ReadonlyArray<'facial_age_estimation' | 'id_document' | 'digital_id' | 'credit_card' | 'world_id'>;
+    };
+    device_platform?: boolean;
+    device_type?: boolean;
+    language?: boolean;
+    audience_include?: boolean;
+    audience_exclude?: boolean;
+    /** Keyword-targeting match types accepted on positive-match terms. */
+    keyword_targets?: {
+        supported_match_types: ReadonlyArray<'broad' | 'phrase' | 'exact'>;
+    };
+    /** Negative-keyword match types accepted. */
+    negative_keywords?: {
+        supported_match_types: ReadonlyArray<'broad' | 'phrase' | 'exact'>;
+    };
+}
+/**
+ * Reporting capabilities the platform supports in `get_media_buy_delivery`.
+ *
+ * `availableDimensions` is the breakdown axes the platform can group
+ * delivery rows by. Vocabulary converged across Scope3 and Prebid.
+ */
+export interface ReportingCapabilities {
+    frequencies: ReadonlyArray<'hourly' | 'daily' | 'weekly'>;
+    expected_delay_minutes: number;
+    timezone: string;
+    metrics: string[];
+    date_range_support: 'date_range' | 'fixed_only';
+    supports_webhooks: boolean;
+    availableDimensions?: ReadonlyArray<'geo' | 'device_type' | 'device_platform' | 'audience' | 'placement' | 'creative' | 'keyword' | 'catalog_item'>;
+}
+/**
+ * Brand-protocol capabilities — projected onto the wire `brand` block of
+ * `get_adcp_capabilities` via the framework's `overrides.brand` deep-merge
+ * seam. Adopters who also implement `BrandRightsPlatform` get
+ * `rights: true` auto-derived; the other four fields (`right_types`,
+ * `available_uses`, `generation_providers`, `description`) are
+ * adopter-declared.
+ *
+ * Wire spec: `protocol/get-adcp-capabilities-response.json#brand`.
+ */
+export type BrandCapabilities = NonNullable<NonNullable<GetAdCPCapabilitiesResponse['brand']>>;
+/**
+ * Compliance-testing capabilities — projected onto the wire-side
+ * `compliance_testing` block of `get_adcp_capabilities` so buyers and
+ * conformance harnesses can discover which `comply_test_controller`
+ * scenarios the agent supports.
+ *
+ * Wire spec: `core/get-adcp-capabilities-response.json#compliance_testing`.
+ *
+ * The `scenarios` array MUST be non-empty when this block is declared
+ * (per the spec). `'list_scenarios'` is implicit — adopters don't need
+ * to enumerate it.
+ */
+export interface ComplianceTestingCapabilities {
+    /**
+     * Scenarios this agent advertises support for. Wire enum is the
+     * spec-narrowed force + simulate set; seed scenarios are
+     * deliberately NOT advertised here (the controller's own
+     * `list_scenarios` response follows the same rule). Adopters who
+     * wire seed adapters get them dispatched correctly at runtime; they
+     * just don't appear in capability discovery. Framework defaults
+     * this from the adopter-supplied `complyTest` adapter set when
+     * omitted.
+     */
+    scenarios?: ReadonlyArray<'force_creative_status' | 'force_account_status' | 'force_media_buy_status' | 'force_session_status' | 'simulate_delivery' | 'simulate_budget_spend'>;
+}
+//# sourceMappingURL=capabilities.d.ts.map

package/dist/lib/server/decisioning/capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/decisioning/capabilities.ts"],"names":[],"mappings":"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"}

package/dist/lib/server/decisioning/capabilities.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * DecisioningCapabilities — single source of truth for `get_adcp_capabilities`
+ * response and any admin UI surface a host wants to render.
+ *
+ * Adopters declare once. Framework wires the wire-protocol response;
+ * adopters' admin tools (or the SDK CLI's `validate_platform_config`) consume
+ * the same dataclass so there's no drift between "what the agent says it
+ * supports" and "what it actually does."
+ *
+ * Status: Preview / 6.0.
+ *
+ * @public
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=capabilities.js.map

package/dist/lib/server/decisioning/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../../../../src/lib/server/decisioning/capabilities.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG"}