@adcp/sdk 5.23.0

package/dist/lib/server/create-adcp-server.d.ts

@@ -0,0 +1,968 @@
+/**
+ * Declarative AdCP server builder.
+ *
+ * `createAdcpServer` wires domain-grouped handler functions to Zod input
+ * schemas, response builders, and account resolution.
+ * Handlers only run when preconditions pass. `get_adcp_capabilities` is
+ * auto-generated from the tools you register.
+ *
+ * For governance on financial tools (create_media_buy, update_media_buy,
+ * activate_signal), use the composable `checkGovernance()` helper inside
+ * your handler — see `governance.ts`.
+ *
+ * @example
+ * ```typescript
+ * import { createAdcpServer, serve } from '@adcp/sdk/server';
+ *
+ * serve(() => createAdcpServer({
+ *   name: 'My Publisher',
+ *   version: '1.0.0',
+ *
+ *   // Second argument carries `toolName` and (when `authenticate` is wired
+ *   // on `serve()`) the caller's `authInfo`. Adapters that front an
+ *   // upstream platform API can use the caller's token here to resolve
+ *   // the platform account in one pass.
+ *   resolveAccount: async (ref, { authInfo }) => db.findAccount(ref, authInfo),
+ *
+ *   mediaBuy: {
+ *     getProducts: async (params, ctx) => ({ products: catalog.search(params) }),
+ *     createMediaBuy: async (params, ctx) => ({
+ *       media_buy_id: `mb_${Date.now()}`,
+ *       packages: [],
+ *     }),
+ *   },
+ * }));
+ * ```
+ */
+import { z } from 'zod';
+import { type AdcpVersion } from '../version';
+import type { ToolCallback } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ZodRawShapeCompat, AnySchema } from '@modelcontextprotocol/sdk/server/zod-compat.js';
+import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+import { type AdcpServer } from './adcp-server';
+import type { TaskStore, TaskMessageQueue } from './tasks';
+import type { AdcpStateStore } from './state-store';
+import { type McpToolResponse } from './responses';
+import type { IdempotencyStore } from './idempotency';
+import { type WebhookEmitParams, type WebhookEmitResult, type WebhookEmitterOptions } from './webhook-emitter';
+import { type TestControllerBridge } from './test-controller-bridge';
+import type { JwksResolver } from '../signing/jwks';
+import type { ReplayStore } from '../signing/replay';
+import type { RevocationStore } from '../signing/revocation';
+import type { ContentDigestPolicy } from '../signing/types';
+import type { GetProductsRequestSchema, CreateMediaBuyRequestSchema, UpdateMediaBuyRequestSchema, GetMediaBuysRequestSchema, GetMediaBuyDeliveryRequestSchema, ProvidePerformanceFeedbackRequestSchema, ListCreativeFormatsRequestSchema, BuildCreativeRequestSchema, GetCreativeDeliveryRequestSchema, ListCreativesRequestSchema, SyncCreativesRequestSchema, GetSignalsRequestSchema, ActivateSignalRequestSchema, ListAccountsRequestSchema, SyncAccountsRequestSchema, SyncGovernanceRequestSchema, GetAccountFinancialsRequestSchema, ReportUsageRequestSchema, SyncEventSourcesRequestSchema, LogEventRequestSchema, SyncAudiencesRequestSchema, SyncCatalogsRequestSchema, CreatePropertyListRequestSchema, UpdatePropertyListRequestSchema, GetPropertyListRequestSchema, ListPropertyListsRequestSchema, DeletePropertyListRequestSchema, ListContentStandardsRequestSchema, GetContentStandardsRequestSchema, CreateContentStandardsRequestSchema, UpdateContentStandardsRequestSchema, CalibrateContentRequestSchema, ValidateContentDeliveryRequestSchema, GetMediaBuyArtifactsRequestSchema, GetCreativeFeaturesRequestSchema, SyncPlansRequestSchema, CheckGovernanceRequestSchema, ReportPlanOutcomeRequestSchema, GetPlanAuditLogsRequestSchema, SIGetOfferingRequestSchema, SIInitiateSessionRequestSchema, SISendMessageRequestSchema, SITerminateSessionRequestSchema, PreviewCreativeRequestSchema, GetBrandIdentityRequestSchema, GetRightsRequestSchema, AcquireRightsRequestSchema } from '../types/schemas.generated';
+import type { AcquireRightsAcquired, AcquireRightsPendingApproval, AcquireRightsRejected, GetBrandIdentitySuccess, GetRightsSuccess } from '../types/core.generated';
+import type { GetProductsResponse, CreateMediaBuySuccess, CreateMediaBuyResponse, UpdateMediaBuySuccess, UpdateMediaBuyResponse, GetMediaBuysResponse, GetMediaBuyDeliveryResponse, ListAccountsResponse, ListCreativeFormatsResponse, ProvidePerformanceFeedbackSuccess, ProvidePerformanceFeedbackResponse, BuildCreativeSuccess, BuildCreativeMultiSuccess, BuildCreativeResponse, GetCreativeDeliveryResponse, ListCreativesResponse, SyncCreativesSuccess, SyncCreativesResponse, GetSignalsResponse, ActivateSignalSuccess, ActivateSignalResponse, GetAdCPCapabilitiesResponse, CreatePropertyListResponse, UpdatePropertyListResponse, GetPropertyListResponse, ListPropertyListsResponse, DeletePropertyListResponse, SyncPlansResponse, CheckGovernanceResponse, ReportPlanOutcomeResponse, GetPlanAuditLogsResponse, SIGetOfferingResponse, SIInitiateSessionResponse, SISendMessageResponse, SITerminateSessionResponse, SyncEventSourcesSuccess, SyncEventSourcesResponse, LogEventSuccess, LogEventResponse, SyncAudiencesSuccess, SyncAudiencesResponse, SyncCatalogsSuccess, SyncCatalogsResponse, SyncAccountsSuccess, SyncAccountsResponse, SyncGovernanceSuccess, SyncGovernanceResponse, GetAccountFinancialsSuccess, GetAccountFinancialsResponse, GetCreativeFeaturesResponse, ReportUsageResponse, PreviewCreativeResponse, AccountReference, ListContentStandardsResponse, GetContentStandardsResponse, CreateContentStandardsResponse, UpdateContentStandardsResponse, CalibrateContentResponse, ValidateContentDeliveryResponse, GetMediaBuyArtifactsResponse } from '../types/tools.generated';
+import type { MediaBuyFeatures, AccountCapabilities, CreativeCapabilities } from '../utils/capabilities';
+import type { MediaChannel } from '../types/tools.generated';
+export interface AdcpLogger {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+/**
+ * Context passed to every handler.
+ *
+ * If the tool has an account ref and `resolveAccount` is configured,
+ * `account` is the resolved account object (guaranteed non-null —
+ * the handler only runs if resolution succeeds).
+ *
+ * If `resolveSessionKey` is configured, `sessionKey` is the scoping key
+ * derived from the request — usually tenant/brand/publisher-account id.
+ * Handlers can pass it to `scopedStore(ctx.store, ctx.sessionKey!)` to get
+ * a session-scoped view that works on any `AdcpStateStore` implementation.
+ */
+export interface HandlerContext<TAccount = unknown> {
+    account?: TAccount;
+    /** Session scoping key derived from the request. Populated when `resolveSessionKey` is configured. */
+    sessionKey?: string;
+    /** State store for persisting domain objects (media buys, accounts, creatives). */
+    store: AdcpStateStore;
+    /**
+     * Authentication info for the caller, when `ServeOptions.authenticate` is configured.
+     * Populated from the MCP SDK's `extra.authInfo`, which `serve()` sets from the auth
+     * principal. Use this to enforce per-principal authorization in handlers.
+     */
+    authInfo?: {
+        token: string;
+        clientId: string;
+        scopes: string[];
+        expiresAt?: number;
+        extra?: Record<string, unknown>;
+    };
+    /**
+     * Emit a signed webhook to a buyer's `push_notification_config.url`.
+     * Populated when `AdcpServerConfig.webhooks` is configured. Handles
+     * RFC 9421 signing, stable `idempotency_key` across retries, and
+     * retry/backoff per adcp#2417 + adcp#2423 + adcp#2478.
+     *
+     * Typical call from inside a completion handler:
+     *
+     *     await ctx.emitWebhook({
+     *       url: push_notification_config.url,
+     *       payload: { task: { task_id, status: 'completed', result } },
+     *       operation_id: `create_media_buy.${media_buy_id}`,
+     *     });
+     */
+    emitWebhook?: (params: WebhookEmitParams) => Promise<WebhookEmitResult>;
+}
+/** Request metadata passed to `resolveSessionKey` so the hook can derive a key from any field. */
+export interface SessionKeyContext<TAccount = unknown> {
+    toolName: AdcpServerToolName;
+    params: Record<string, unknown>;
+    account?: TAccount;
+}
+/**
+ * Request context passed to `resolveAccount` so the resolver can inspect the
+ * authenticated principal at resolution time. This matters for adapters that
+ * front an upstream platform API (Snap, Meta, TikTok, retail media networks)
+ * where the upstream account lookup requires the caller's platform OAuth
+ * token — forwarding `authInfo` into `resolveAccount` lets the resolver put
+ * platform identifiers (ad_account_id, upstream token state) directly on the
+ * resolved `TAccount` rather than re-resolving inside every handler.
+ */
+export interface ResolveAccountContext {
+    /** The AdCP tool being called. */
+    toolName: AdcpServerToolName;
+    /**
+     * Authentication info for the caller, populated from `extra.authInfo` on the
+     * MCP request. Undefined when no `authenticate` is configured on `serve()`.
+     */
+    authInfo?: HandlerContext['authInfo'];
+}
+/**
+ * Narrow `ctx.sessionKey` from `string | undefined` to `string`. Use this in
+ * handlers that require session scoping so you don't litter `!` assertions:
+ *
+ * ```ts
+ * const sessionKey = requireSessionKey(ctx);
+ * const sessionStore = scopedStore(ctx.store, sessionKey);
+ * ```
+ *
+ * Throws a `SERVICE_UNAVAILABLE`-style error if `sessionKey` is missing — typically
+ * meaning `resolveSessionKey` isn't configured or returned `undefined` for this tool.
+ */
+export declare function requireSessionKey<TAccount = unknown>(ctx: HandlerContext<TAccount>): string;
+/**
+ * Per-tool param / result / response types.
+ *
+ * `result` is the narrow success arm — what the framework's response
+ * builders (`mediaBuyResponse`, `syncCreativesResponse`, ...) expect.
+ * `response` is the full AdCP response union (Success | Error | Submitted).
+ * Handlers can return either shape: adapter patterns that produce
+ * `Result<FooResponse, ...>` now type-check without `as any`, and the
+ * dispatcher narrows Error / Submitted arms at runtime so the response
+ * builder only fires on the Success arm.
+ */
+export interface AdcpToolMap {
+    get_products: {
+        params: z.input<typeof GetProductsRequestSchema>;
+        result: GetProductsResponse;
+        response: GetProductsResponse;
+    };
+    create_media_buy: {
+        params: z.input<typeof CreateMediaBuyRequestSchema>;
+        result: CreateMediaBuySuccess;
+        response: CreateMediaBuyResponse;
+    };
+    update_media_buy: {
+        params: z.input<typeof UpdateMediaBuyRequestSchema>;
+        result: UpdateMediaBuySuccess;
+        response: UpdateMediaBuyResponse;
+    };
+    get_media_buys: {
+        params: z.input<typeof GetMediaBuysRequestSchema>;
+        result: GetMediaBuysResponse;
+        response: GetMediaBuysResponse;
+    };
+    get_media_buy_delivery: {
+        params: z.input<typeof GetMediaBuyDeliveryRequestSchema>;
+        result: GetMediaBuyDeliveryResponse;
+        response: GetMediaBuyDeliveryResponse;
+    };
+    provide_performance_feedback: {
+        params: z.input<typeof ProvidePerformanceFeedbackRequestSchema>;
+        result: ProvidePerformanceFeedbackSuccess;
+        response: ProvidePerformanceFeedbackResponse;
+    };
+    list_creative_formats: {
+        params: z.input<typeof ListCreativeFormatsRequestSchema>;
+        result: ListCreativeFormatsResponse;
+        response: ListCreativeFormatsResponse;
+    };
+    build_creative: {
+        params: z.input<typeof BuildCreativeRequestSchema>;
+        result: BuildCreativeSuccess | BuildCreativeMultiSuccess;
+        response: BuildCreativeResponse;
+    };
+    preview_creative: {
+        params: z.input<typeof PreviewCreativeRequestSchema>;
+        result: PreviewCreativeResponse;
+        response: PreviewCreativeResponse;
+    };
+    get_creative_delivery: {
+        params: z.input<typeof GetCreativeDeliveryRequestSchema>;
+        result: GetCreativeDeliveryResponse;
+        response: GetCreativeDeliveryResponse;
+    };
+    list_creatives: {
+        params: z.input<typeof ListCreativesRequestSchema>;
+        result: ListCreativesResponse;
+        response: ListCreativesResponse;
+    };
+    sync_creatives: {
+        params: z.input<typeof SyncCreativesRequestSchema>;
+        result: SyncCreativesSuccess;
+        response: SyncCreativesResponse;
+    };
+    get_signals: {
+        params: z.input<typeof GetSignalsRequestSchema>;
+        result: GetSignalsResponse;
+        response: GetSignalsResponse;
+    };
+    activate_signal: {
+        params: z.input<typeof ActivateSignalRequestSchema>;
+        result: ActivateSignalSuccess;
+        response: ActivateSignalResponse;
+    };
+    list_accounts: {
+        params: z.input<typeof ListAccountsRequestSchema>;
+        result: ListAccountsResponse;
+        response: ListAccountsResponse;
+    };
+    sync_accounts: {
+        params: z.input<typeof SyncAccountsRequestSchema>;
+        result: SyncAccountsSuccess;
+        response: SyncAccountsResponse;
+    };
+    sync_governance: {
+        params: z.input<typeof SyncGovernanceRequestSchema>;
+        result: SyncGovernanceSuccess;
+        response: SyncGovernanceResponse;
+    };
+    get_account_financials: {
+        params: z.input<typeof GetAccountFinancialsRequestSchema>;
+        result: GetAccountFinancialsSuccess;
+        response: GetAccountFinancialsResponse;
+    };
+    report_usage: {
+        params: z.input<typeof ReportUsageRequestSchema>;
+        result: ReportUsageResponse;
+        response: ReportUsageResponse;
+    };
+    sync_event_sources: {
+        params: z.input<typeof SyncEventSourcesRequestSchema>;
+        result: SyncEventSourcesSuccess;
+        response: SyncEventSourcesResponse;
+    };
+    log_event: {
+        params: z.input<typeof LogEventRequestSchema>;
+        result: LogEventSuccess;
+        response: LogEventResponse;
+    };
+    sync_audiences: {
+        params: z.input<typeof SyncAudiencesRequestSchema>;
+        result: SyncAudiencesSuccess;
+        response: SyncAudiencesResponse;
+    };
+    sync_catalogs: {
+        params: z.input<typeof SyncCatalogsRequestSchema>;
+        result: SyncCatalogsSuccess;
+        response: SyncCatalogsResponse;
+    };
+    create_property_list: {
+        params: z.input<typeof CreatePropertyListRequestSchema>;
+        result: CreatePropertyListResponse;
+        response: CreatePropertyListResponse;
+    };
+    update_property_list: {
+        params: z.input<typeof UpdatePropertyListRequestSchema>;
+        result: UpdatePropertyListResponse;
+        response: UpdatePropertyListResponse;
+    };
+    get_property_list: {
+        params: z.input<typeof GetPropertyListRequestSchema>;
+        result: GetPropertyListResponse;
+        response: GetPropertyListResponse;
+    };
+    list_property_lists: {
+        params: z.input<typeof ListPropertyListsRequestSchema>;
+        result: ListPropertyListsResponse;
+        response: ListPropertyListsResponse;
+    };
+    delete_property_list: {
+        params: z.input<typeof DeletePropertyListRequestSchema>;
+        result: DeletePropertyListResponse;
+        response: DeletePropertyListResponse;
+    };
+    list_content_standards: {
+        params: z.input<typeof ListContentStandardsRequestSchema>;
+        result: ListContentStandardsResponse;
+        response: ListContentStandardsResponse;
+    };
+    get_content_standards: {
+        params: z.input<typeof GetContentStandardsRequestSchema>;
+        result: GetContentStandardsResponse;
+        response: GetContentStandardsResponse;
+    };
+    create_content_standards: {
+        params: z.input<typeof CreateContentStandardsRequestSchema>;
+        result: CreateContentStandardsResponse;
+        response: CreateContentStandardsResponse;
+    };
+    update_content_standards: {
+        params: z.input<typeof UpdateContentStandardsRequestSchema>;
+        result: UpdateContentStandardsResponse;
+        response: UpdateContentStandardsResponse;
+    };
+    calibrate_content: {
+        params: z.input<typeof CalibrateContentRequestSchema>;
+        result: CalibrateContentResponse;
+        response: CalibrateContentResponse;
+    };
+    validate_content_delivery: {
+        params: z.input<typeof ValidateContentDeliveryRequestSchema>;
+        result: ValidateContentDeliveryResponse;
+        response: ValidateContentDeliveryResponse;
+    };
+    get_media_buy_artifacts: {
+        params: z.input<typeof GetMediaBuyArtifactsRequestSchema>;
+        result: GetMediaBuyArtifactsResponse;
+        response: GetMediaBuyArtifactsResponse;
+    };
+    get_creative_features: {
+        params: z.input<typeof GetCreativeFeaturesRequestSchema>;
+        result: GetCreativeFeaturesResponse;
+        response: GetCreativeFeaturesResponse;
+    };
+    sync_plans: {
+        params: z.input<typeof SyncPlansRequestSchema>;
+        result: SyncPlansResponse;
+        response: SyncPlansResponse;
+    };
+    check_governance: {
+        params: z.input<typeof CheckGovernanceRequestSchema>;
+        result: CheckGovernanceResponse;
+        response: CheckGovernanceResponse;
+    };
+    report_plan_outcome: {
+        params: z.input<typeof ReportPlanOutcomeRequestSchema>;
+        result: ReportPlanOutcomeResponse;
+        response: ReportPlanOutcomeResponse;
+    };
+    get_plan_audit_logs: {
+        params: z.input<typeof GetPlanAuditLogsRequestSchema>;
+        result: GetPlanAuditLogsResponse;
+        response: GetPlanAuditLogsResponse;
+    };
+    si_get_offering: {
+        params: z.input<typeof SIGetOfferingRequestSchema>;
+        result: SIGetOfferingResponse;
+        response: SIGetOfferingResponse;
+    };
+    si_initiate_session: {
+        params: z.input<typeof SIInitiateSessionRequestSchema>;
+        result: SIInitiateSessionResponse;
+        response: SIInitiateSessionResponse;
+    };
+    si_send_message: {
+        params: z.input<typeof SISendMessageRequestSchema>;
+        result: SISendMessageResponse;
+        response: SISendMessageResponse;
+    };
+    si_terminate_session: {
+        params: z.input<typeof SITerminateSessionRequestSchema>;
+        result: SITerminateSessionResponse;
+        response: SITerminateSessionResponse;
+    };
+    get_brand_identity: {
+        params: z.input<typeof GetBrandIdentityRequestSchema>;
+        result: GetBrandIdentitySuccess;
+        response: GetBrandIdentitySuccess;
+    };
+    get_rights: {
+        params: z.input<typeof GetRightsRequestSchema>;
+        result: GetRightsSuccess;
+        response: GetRightsSuccess;
+    };
+    acquire_rights: {
+        params: z.input<typeof AcquireRightsRequestSchema>;
+        result: AcquireRightsAcquired | AcquireRightsPendingApproval | AcquireRightsRejected;
+        response: AcquireRightsAcquired | AcquireRightsPendingApproval | AcquireRightsRejected;
+    };
+}
+export type AdcpServerToolName = keyof AdcpToolMap;
+/** Handler that receives validated params and a resolved context.
+ *
+ *  Return any of:
+ *  - The narrow Success arm (`result`) — framework applies the response builder.
+ *  - The full response union (`response` = Success | Error | Submitted) — the
+ *    dispatcher narrows Error / Submitted arms at runtime. Useful for adapters
+ *    that already produce a `Result<FooResponse, ...>` and don't want to
+ *    pre-narrow.
+ *  - A pre-formatted `McpToolResponse` (e.g. from `adcpError(...)`) — passed
+ *    through unchanged.
+ */
+type DomainHandler<K extends AdcpServerToolName, TAccount> = (params: AdcpToolMap[K]['params'], ctx: HandlerContext<TAccount>) => Promise<AdcpToolMap[K]['result'] | AdcpToolMap[K]['response'] | McpToolResponse>;
+export interface MediaBuyHandlers<TAccount = unknown> {
+    getProducts?: DomainHandler<'get_products', TAccount>;
+    createMediaBuy?: DomainHandler<'create_media_buy', TAccount>;
+    updateMediaBuy?: DomainHandler<'update_media_buy', TAccount>;
+    getMediaBuys?: DomainHandler<'get_media_buys', TAccount>;
+    getMediaBuyDelivery?: DomainHandler<'get_media_buy_delivery', TAccount>;
+    providePerformanceFeedback?: DomainHandler<'provide_performance_feedback', TAccount>;
+    listCreativeFormats?: DomainHandler<'list_creative_formats', TAccount>;
+    syncCreatives?: DomainHandler<'sync_creatives', TAccount>;
+    listCreatives?: DomainHandler<'list_creatives', TAccount>;
+}
+export interface EventTrackingHandlers<TAccount = unknown> {
+    syncEventSources?: DomainHandler<'sync_event_sources', TAccount>;
+    logEvent?: DomainHandler<'log_event', TAccount>;
+    syncAudiences?: DomainHandler<'sync_audiences', TAccount>;
+    syncCatalogs?: DomainHandler<'sync_catalogs', TAccount>;
+}
+export interface SignalsHandlers<TAccount = unknown> {
+    getSignals?: DomainHandler<'get_signals', TAccount>;
+    activateSignal?: DomainHandler<'activate_signal', TAccount>;
+}
+export interface CreativeHandlers<TAccount = unknown> {
+    listCreativeFormats?: DomainHandler<'list_creative_formats', TAccount>;
+    buildCreative?: DomainHandler<'build_creative', TAccount>;
+    previewCreative?: DomainHandler<'preview_creative', TAccount>;
+    listCreatives?: DomainHandler<'list_creatives', TAccount>;
+    syncCreatives?: DomainHandler<'sync_creatives', TAccount>;
+    getCreativeDelivery?: DomainHandler<'get_creative_delivery', TAccount>;
+}
+export interface GovernanceHandlers<TAccount = unknown> {
+    createPropertyList?: DomainHandler<'create_property_list', TAccount>;
+    updatePropertyList?: DomainHandler<'update_property_list', TAccount>;
+    getPropertyList?: DomainHandler<'get_property_list', TAccount>;
+    listPropertyLists?: DomainHandler<'list_property_lists', TAccount>;
+    deletePropertyList?: DomainHandler<'delete_property_list', TAccount>;
+    listContentStandards?: DomainHandler<'list_content_standards', TAccount>;
+    getContentStandards?: DomainHandler<'get_content_standards', TAccount>;
+    createContentStandards?: DomainHandler<'create_content_standards', TAccount>;
+    updateContentStandards?: DomainHandler<'update_content_standards', TAccount>;
+    calibrateContent?: DomainHandler<'calibrate_content', TAccount>;
+    validateContentDelivery?: DomainHandler<'validate_content_delivery', TAccount>;
+    getMediaBuyArtifacts?: DomainHandler<'get_media_buy_artifacts', TAccount>;
+    getCreativeFeatures?: DomainHandler<'get_creative_features', TAccount>;
+    syncPlans?: DomainHandler<'sync_plans', TAccount>;
+    checkGovernance?: DomainHandler<'check_governance', TAccount>;
+    reportPlanOutcome?: DomainHandler<'report_plan_outcome', TAccount>;
+    getPlanAuditLogs?: DomainHandler<'get_plan_audit_logs', TAccount>;
+}
+export interface AccountHandlers<TAccount = unknown> {
+    listAccounts?: DomainHandler<'list_accounts', TAccount>;
+    syncAccounts?: DomainHandler<'sync_accounts', TAccount>;
+    syncGovernance?: DomainHandler<'sync_governance', TAccount>;
+    getAccountFinancials?: DomainHandler<'get_account_financials', TAccount>;
+    reportUsage?: DomainHandler<'report_usage', TAccount>;
+}
+export interface SponsoredIntelligenceHandlers<TAccount = unknown> {
+    getOffering?: DomainHandler<'si_get_offering', TAccount>;
+    initiateSession?: DomainHandler<'si_initiate_session', TAccount>;
+    sendMessage?: DomainHandler<'si_send_message', TAccount>;
+    terminateSession?: DomainHandler<'si_terminate_session', TAccount>;
+}
+/**
+ * Brand rights covers identity and licensing workflows. `update_rights` and
+ * `creative_approval` are intentionally not exposed here — the spec models
+ * creative approval as a webhook (POST to `approval_webhook` returned from
+ * `acquire_rights`), and neither has published JSON schemas yet. Implement
+ * those as regular HTTP endpoints outside the MCP surface until schemas land.
+ */
+export interface BrandRightsHandlers<TAccount = unknown> {
+    getBrandIdentity?: DomainHandler<'get_brand_identity', TAccount>;
+    getRights?: DomainHandler<'get_rights', TAccount>;
+    acquireRights?: DomainHandler<'acquire_rights', TAccount>;
+}
+export interface AdcpCapabilitiesConfig {
+    major_versions?: number[];
+    features?: Partial<MediaBuyFeatures>;
+    account?: Partial<AccountCapabilities>;
+    creative?: Partial<CreativeCapabilities>;
+    extensions_supported?: string[];
+    /**
+     * RFC 9421 request-signing verifier capability. See
+     * docs/building/implementation/security.mdx#signed-requests-transport-layer.
+     * Emitted verbatim in `get_adcp_capabilities.request_signing`. Omit unless
+     * the agent actually verifies incoming signatures — a `supported: true`
+     * claim without a working verifier is graded as FAIL by the conformance
+     * runner (see `@adcp/sdk/testing/storyboard/request-signing`).
+     */
+    request_signing?: NonNullable<GetAdCPCapabilitiesResponse['request_signing']>;
+    /**
+     * Specialism claims the agent supports. Each entry maps to a storyboard
+     * bundle under `/compliance/{version}/specialisms/{id}/`; the AAO
+     * compliance runner executes the matching storyboards to verify. Only
+     * list specialisms the agent actually implements.
+     */
+    specialisms?: NonNullable<GetAdCPCapabilitiesResponse['specialisms']>;
+    /**
+     * Seller-declared idempotency replay window, required on `get_adcp_capabilities`
+     * responses per AdCP spec. Defaults to 86400 (24h). Spec bounds are 3600
+     * (1h) to 604800 (7d); `clampReplayTtl` enforces the range on output.
+     *
+     * When using `createIdempotencyStore` from `@adcp/sdk/server`, omit
+     * this — the framework reads `idempotency.ttlSeconds` from the wired
+     * store so the declared capability always matches actual behavior.
+     */
+    idempotency?: {
+        replay_ttl_seconds?: number;
+    };
+    portfolio?: {
+        publisher_domains: string[];
+        primary_channels?: MediaChannel[];
+        primary_countries?: string[];
+        description?: string;
+        advertising_policies?: string;
+    };
+    /**
+     * Per-domain capability blocks deep-merged on top of the framework's
+     * auto-derived response. Use when you need to surface fields the top-level
+     * `AdcpCapabilitiesConfig` doesn't model — execution.targeting,
+     * audience_targeting, content_standards channels, conversion_tracking
+     * identifier types, compliance_testing scenarios, etc.
+     *
+     * Deep-merge semantics:
+     * - nested objects merge recursively;
+     * - arrays REPLACE (not concat) so callers stay in control of cardinality;
+     * - primitive overrides replace the auto-derived value.
+     *
+     * Top-level fields the framework owns (`adcp`, `supported_protocols`,
+     * `specialisms`, `extensions_supported`) are not accepted here — configure
+     * them via their dedicated fields on {@link AdcpCapabilitiesConfig}.
+     */
+    overrides?: AdcpCapabilitiesOverrides;
+}
+/**
+ * Per-domain capability overrides. See {@link AdcpCapabilitiesConfig.overrides}.
+ *
+ * Each field accepts the same shape as the corresponding block on
+ * {@link GetAdCPCapabilitiesResponse}. A value of `null` explicitly removes
+ * the auto-derived block; `undefined` (omission) is a no-op.
+ *
+ * **Values must be JSON-serializable plain objects.** Class instances, `Date`,
+ * `Map`, `Set`, or any value with a non-`Object.prototype` prototype are
+ * treated as opaque leaves and replace their target rather than merging.
+ */
+export interface AdcpCapabilitiesOverrides {
+    media_buy?: Partial<NonNullable<GetAdCPCapabilitiesResponse['media_buy']>> | null;
+    creative?: Partial<NonNullable<GetAdCPCapabilitiesResponse['creative']>> | null;
+    signals?: Partial<NonNullable<GetAdCPCapabilitiesResponse['signals']>> | null;
+    governance?: Partial<NonNullable<GetAdCPCapabilitiesResponse['governance']>> | null;
+    brand?: Partial<NonNullable<GetAdCPCapabilitiesResponse['brand']>> | null;
+    sponsored_intelligence?: Partial<NonNullable<GetAdCPCapabilitiesResponse['sponsored_intelligence']>> | null;
+    account?: Partial<NonNullable<GetAdCPCapabilitiesResponse['account']>> | null;
+    compliance_testing?: GetAdCPCapabilitiesResponse['compliance_testing'] | null;
+    webhook_signing?: GetAdCPCapabilitiesResponse['webhook_signing'] | null;
+    identity?: GetAdCPCapabilitiesResponse['identity'] | null;
+    request_signing?: GetAdCPCapabilitiesResponse['request_signing'] | null;
+}
+/**
+ * Inputs for the auto-wired RFC 9421 request-signature verifier. When set on
+ * {@link AdcpServerConfig}, `createAdcpServer` builds an Express-shaped
+ * verifier middleware and attaches it to the returned `McpServer` via
+ * {@link ADCP_PRE_TRANSPORT}. `serve()` discovers the attached middleware and
+ * mounts it as the transport-layer `preTransport` hook, so every inbound MCP
+ * request passes the verifier before reaching the JSON-RPC router.
+ *
+ * A seller that declares the `signed-requests` specialism in
+ * `capabilities.specialisms` MUST provide this config, and vice-versa — both
+ * together or neither. `createAdcpServer` throws at construction time when
+ * only one is set, closing the footgun where claiming the specialism
+ * accepts unsigned mutating traffic.
+ *
+ * `jwks`, `replayStore`, and `revocationStore` should be hoisted outside
+ * the agent factory so a single verifier instance serves every request —
+ * otherwise each request would build a fresh replay store and the rate-
+ * abuse / replay-detection guards would be per-request (i.e. broken).
+ */
+export interface SignedRequestsConfig {
+    /** Resolves verification keys by `keyid`. */
+    jwks: JwksResolver;
+    /** Stores `(keyid, signature-bytes, expires)` tuples for replay detection. */
+    replayStore: ReplayStore;
+    /** Consulted for revoked `kid` / `jti` before accepting a signature. */
+    revocationStore: RevocationStore;
+    /**
+     * Operation names that MUST arrive signed. Defaults to every mutating
+     * AdCP tool (per the framework's {@link MUTATING_TASKS}). Read-only tools
+     * are optional — callers can sign them for authenticity but the verifier
+     * accepts unsigned traffic outside this list.
+     */
+    required_for?: string[];
+    /** Default `'either'` — accept signatures with or without Content-Digest. */
+    covers_content_digest?: ContentDigestPolicy;
+    /**
+     * Resolve the `agent_url` claim the verifier stamps on successful results.
+     * Useful when a single seller hosts multiple brands and the buyer's
+     * signing key is scoped to a brand identifier rather than the root.
+     */
+    agentUrlForKeyid?: (keyid: string) => string | undefined;
+}
+/**
+ * Symbol under which `createAdcpServer` attaches the auto-wired `preTransport`
+ * function to the returned `McpServer`. `serve()` reads this symbol to mount
+ * the verifier. Consumers typically don't need to touch it; it's exported for
+ * tests and for downstream frameworks that want the same wiring.
+ */
+export declare const ADCP_PRE_TRANSPORT: unique symbol;
+/**
+ * Diagnostic snapshot of the signed-requests wiring on a returned server.
+ * Read via `server[ADCP_SIGNED_REQUESTS_STATE]` so integration tests and
+ * operator boot diagnostics can assert on the claim/config pairing without
+ * parsing log output. Populated on every `createAdcpServer` call.
+ */
+export interface AdcpSignedRequestsState {
+    /** True when `signedRequests: {...}` was passed and the verifier is auto-wired. */
+    autoWired: boolean;
+    /** True when `capabilities.specialisms` includes `'signed-requests'`. */
+    specialismClaimed: boolean;
+    /** True when `capabilities.request_signing.supported === true`. */
+    capabilitySupported: boolean;
+    /**
+     * Non-fatal mismatch state. `'ok'` when wiring + claim + supported are
+     * all aligned (or all off); `'claim_without_config'` when the claim is
+     * set but no `signedRequests` config was passed (legacy manual
+     * `serve({ preTransport })` path — logged but not thrown).
+     */
+    mismatch: 'ok' | 'claim_without_config';
+}
+/**
+ * Symbol under which `createAdcpServer` attaches the `AdcpSignedRequestsState`
+ * snapshot. Use `server[ADCP_SIGNED_REQUESTS_STATE]` to inspect wiring from
+ * tests or boot diagnostics.
+ */
+export declare const ADCP_SIGNED_REQUESTS_STATE: unique symbol;
+/**
+ * Shape of the preTransport function attached by `createAdcpServer` when
+ * `signedRequests` is configured. Returns `true` if the middleware has already
+ * sent a response (e.g., 401 on verification failure), `false` to continue
+ * into MCP dispatch.
+ */
+export type AdcpPreTransport = (req: import('http').IncomingMessage & {
+    rawBody?: string;
+}, res: import('http').ServerResponse) => Promise<boolean>;
+/**
+ * Declarative registration for a tool outside {@link AdcpToolMap} — seller
+ * extensions (e.g. collection-list helpers), test-harness endpoints
+ * (`comply_test_controller`), or AdCP surfaces whose JSON Schemas haven't
+ * landed in the framework yet (`creative_approval`, `update_rights`).
+ *
+ * These tools **bypass the framework's spec-tool pipeline**:
+ * idempotency middleware, governance pre-checks, account resolution,
+ * and response wrapping are all skipped. The handler receives the
+ * SDK-validated arguments and must return a `CallToolResult` directly.
+ * If you need any of those behaviors, call the framework helpers from
+ * inside the handler (e.g., `checkGovernance(...)`, `adcpError(...)`).
+ *
+ * Type parameters match the SDK's `McpServer.registerTool` signature so
+ * argument and response types infer from the declared schemas.
+ */
+export interface AdcpCustomToolConfig<InputArgs extends undefined | ZodRawShapeCompat | AnySchema = undefined, OutputArgs extends ZodRawShapeCompat | AnySchema | undefined = undefined> {
+    /** Human-readable description — surfaced in `tools/list`. */
+    description?: string;
+    /** Optional title hint for the MCP inspector. */
+    title?: string;
+    /** Zod raw shape or schema for argument validation. */
+    inputSchema?: InputArgs;
+    /**
+     * Zod raw shape or schema for the declared response payload.
+     *
+     * Forwarded verbatim to `registerTool`. The MCP SDK validates every
+     * non-error response's `structuredContent` against this schema on the
+     * server AND on the buyer's client (the latter fires regardless of
+     * `isError` — see the `NOTE on outputSchema` block earlier in this
+     * file). Framework-registered AdCP tools skip this field for that
+     * reason; custom tools opt in here and own the trade-off.
+     *
+     * Footgun: a too-strict schema (e.g. `z.never()`, or one that
+     * accidentally rejects the caller's own valid shape) turns the tool
+     * into a silent client-side validation error for every buyer. The
+     * seller sees a successful response go out; the buyer receives an
+     * `Output validation error`. Test against a real buyer call before
+     * relying on this.
+     */
+    outputSchema?: OutputArgs;
+    /** Tool annotations (readOnlyHint / destructiveHint / idempotentHint / openWorldHint). */
+    annotations?: ToolAnnotations;
+    /**
+     * Tool handler. Gets SDK-validated `args` based on `inputSchema` and
+     * must return a `CallToolResult`. Use `capabilitiesResponse`,
+     * `mediaBuyResponse`, `adcpError`, or a hand-built `{ content, structuredContent? }`.
+     */
+    handler: ToolCallback<InputArgs>;
+}
+export interface AdcpServerConfig<TAccount = unknown> {
+    name: string;
+    version: string;
+    /**
+     * AdCP protocol version this server speaks. Defaults to {@link ADCP_VERSION}
+     * — the GA version the SDK ships against. Override to pin to an older
+     * stable (e.g., `'3.0.0'`) or opt into a beta channel (`'3.1.0-beta.1'`)
+     * once that registry ships.
+     *
+     * Not the same as `version` (the publisher's app version, e.g., `'1.4.2'`).
+     *
+     * Stage 2 plumbs the option through and validates it at construction
+     * time; cross-major pins (e.g. `'4.0.0-beta.1'` while the SDK ships
+     * against major 3) throw `ConfigurationError`. Stage 3 wires per-instance
+     * schema/validator selection off this field.
+     *
+     * Typed as `AdcpVersion | (string & {})` so editors autocomplete
+     * canonical values from {@link COMPATIBLE_ADCP_VERSIONS} while still
+     * accepting forward-compatible strings.
+     */
+    adcpVersion?: AdcpVersion | (string & {});
+    /**
+     * Resolve an account from an AccountReference.
+     * Called on every request that has an `account` field.
+     * Return null if the account doesn't exist — framework responds ACCOUNT_NOT_FOUND.
+     *
+     * The second argument carries the AdCP `toolName` and, when `serve()` is
+     * configured with `authenticate`, the caller's `authInfo`. Adapters that
+     * need the caller's upstream platform token to look up the account can
+     * read it from `ctx.authInfo` here and attach anything they want to the
+     * resolved account.
+     *
+     * Single-argument resolvers (`async (ref) => ...`) are valid — TypeScript
+     * allows a shorter parameter list.
+     *
+     * **Do not persist `authInfo` outside the returned account object.** The
+     * framework makes no isolation guarantees about values closed over by the
+     * resolver; caching `authInfo` into shared state can leak the caller's
+     * principal across requests.
+     */
+    resolveAccount?: (ref: AccountReference, ctx: ResolveAccountContext) => Promise<TAccount | null>;
+    /**
+     * Derive a session-scoping key from the request. Populates `ctx.sessionKey`
+     * so handlers don't re-implement key derivation (tenant, brand, publisher
+     * account id, etc.). Called after `resolveAccount`, so the resolved account
+     * is available.
+     *
+     * Return `undefined` to leave `ctx.sessionKey` unset (e.g., for anonymous
+     * or public tools).
+     */
+    resolveSessionKey?: (ctx: SessionKeyContext<TAccount>) => string | undefined | Promise<string | undefined>;
+    /**
+     * When `true`, framework-produced `SERVICE_UNAVAILABLE` errors include the
+     * underlying `err.message` in `details.reason` (helpful in dev, but can leak
+     * DB driver messages, file paths, or schema info to remote callers).
+     *
+     * Defaults:
+     *   - `NODE_ENV === 'production'` → `false` (safe default for live agents).
+     *   - Otherwise → `true` (dev/test/CI surface the cause chain so
+     *     `SERVICE_UNAVAILABLE: encountered an internal error` becomes
+     *     `SERVICE_UNAVAILABLE: Cannot find module '@adcp/sdk/foo'`.
+     *     Matrix runs spent weeks on opaque SU errors before this default flipped).
+     *
+     * Explicit `exposeErrorDetails: true | false` always wins.
+     */
+    exposeErrorDetails?: boolean;
+    /** Logger for framework decisions. Defaults to no-op. */
+    logger?: AdcpLogger;
+    /**
+     * State store for persisting domain objects across requests.
+     * Defaults to InMemoryStateStore. Use PostgresStateStore for production.
+     */
+    stateStore?: AdcpStateStore;
+    mediaBuy?: MediaBuyHandlers<TAccount>;
+    signals?: SignalsHandlers<TAccount>;
+    creative?: CreativeHandlers<TAccount>;
+    governance?: GovernanceHandlers<TAccount>;
+    accounts?: AccountHandlers<TAccount>;
+    eventTracking?: EventTrackingHandlers<TAccount>;
+    sponsoredIntelligence?: SponsoredIntelligenceHandlers<TAccount>;
+    brandRights?: BrandRightsHandlers<TAccount>;
+    /** Explicit capabilities overrides (merged on top of auto-detected). */
+    capabilities?: AdcpCapabilitiesConfig;
+    /**
+     * Idempotency store for mutating requests. When configured, the framework:
+     *
+     * - Requires `idempotency_key` on every mutating request (returns
+     *   `INVALID_REQUEST` when missing)
+     * - Replays the cached response for matching `(principal, key, payload)`
+     *   and injects `replayed: true` on the envelope
+     * - Returns `IDEMPOTENCY_CONFLICT` for same-key-different-payload
+     * - Returns `IDEMPOTENCY_EXPIRED` when the key is past the TTL
+     * - Declares `adcp.idempotency.replay_ttl_seconds` on `get_adcp_capabilities`
+     *
+     * Scoping: by default uses `ctx.sessionKey` as the principal. Override
+     * via `resolveIdempotencyPrincipal`.
+     *
+     * Pass the literal string `'disabled'` to suppress idempotency
+     * enforcement end-to-end: schema validation tolerates a missing
+     * `idempotency_key` on mutating tools, the replay/conflict middleware
+     * is skipped, and the missing-store guardrail log is silenced. Intended
+     * for non-production test fleets that don't model idempotency replay
+     * — production servers should always wire a real store. The framework
+     * logs an info-level warning at construction when this mode is used
+     * outside `NODE_ENV=test` so the choice is visible.
+     */
+    idempotency?: IdempotencyStore | 'disabled';
+    /**
+     * Derive the idempotency principal from the handler context, the
+     * request params, and the tool name. Defaults to `ctx.sessionKey`. Two
+     * buyers that share a sessionKey would share cache entries — if that's
+     * not what you want, return something more specific (e.g., an
+     * operator_id) from this hook.
+     *
+     * Receives `params` and `toolName` so callers can fold request-shape
+     * identity into the principal when needed (e.g., scoping by a custom
+     * tenant header). For per-session scoping (`si_send_message`), the
+     * framework already folds `params.session_id` into the scope tuple —
+     * the principal is still the authenticated buyer.
+     */
+    resolveIdempotencyPrincipal?: (ctx: HandlerContext<TAccount>, params: Record<string, unknown>, toolName: AdcpServerToolName) => string | undefined;
+    instructions?: string;
+    taskStore?: TaskStore;
+    taskMessageQueue?: TaskMessageQueue;
+    /**
+     * Webhook-emission config. When set, `ctx.emitWebhook` is populated on
+     * every handler's context — handlers post signed, retried,
+     * idempotency-stable webhooks without hand-rolling the pipeline. Omit
+     * if your server never emits webhooks.
+     *
+     * Provide exactly one of `signerKey` (in-process JWK) or `signerProvider`
+     * (KMS-backed async signing). The signing key or provider key MUST have
+     * `adcp_use: "webhook-signing"` — a request-signing key is a conformance
+     * violation per adcp#2423 (key purpose discriminator). Publishers publishing
+     * their JWKS at the `jwks_uri` on brand.json's `agents[]` entry reuse the
+     * same key across every buyer they deliver to.
+     */
+    webhooks?: Pick<WebhookEmitterOptions, 'signerKey' | 'signerProvider' | 'retries' | 'idempotencyKeyStore' | 'generateIdempotencyKey' | 'fetch' | 'userAgent' | 'tag'> & {
+        /** Observability: emitter-wide onAttempt hook. */
+        onAttempt?: WebhookEmitterOptions['onAttempt'];
+        /** Observability: emitter-wide onAttemptResult hook. */
+        onAttemptResult?: WebhookEmitterOptions['onAttemptResult'];
+    };
+    /**
+     * Auto-wire the RFC 9421 request-signature verifier onto the HTTP transport.
+     * When set together with `capabilities.specialisms` containing
+     * `signed-requests`, `serve()` mounts the verifier as `preTransport` so
+     * every inbound MCP request is verified before JSON-RPC dispatch. Setting
+     * one without the other throws at construction time — the spec requires
+     * the specialism claim and a working verifier to stay in lock-step.
+     *
+     * Omit entirely when the seller doesn't verify inbound signatures. Servers
+     * that wire the verifier manually via `serve({ preTransport })` are
+     * unaffected — auto-wiring only kicks in through this field.
+     */
+    signedRequests?: SignedRequestsConfig;
+    /**
+     * Schema-driven validation of requests and responses against the bundled
+     * AdCP JSON schemas. When enabled, the dispatcher rejects bad requests
+     * with `VALIDATION_ERROR` before the handler runs and catches drift in
+     * handler-returned responses before they leave the server.
+     *
+     * Defaults:
+     *   - When `NODE_ENV === 'production'` → both sides `'off'` (zero overhead
+     *     in prod; trust the handler after its test suite has exercised it).
+     *   - Otherwise (dev, test, CI) → `responses: 'strict'`, `requests: 'warn'`.
+     *     Strict on responses turns handler-returned drift into a
+     *     `VALIDATION_ERROR` with the offending field path — surfaces the
+     *     "handler returned a sparse object that fails the wire schema" class
+     *     of bug at development time instead of letting it ship and surface
+     *     downstream as a cryptic `SERVICE_UNAVAILABLE` or `oneOf`
+     *     discriminator failure. Warn on requests logs incoming payloads that
+     *     don't match the bundled AdCP schema but still dispatches, so
+     *     upstream schema tightenings show up as diagnostics without breaking
+     *     clients that haven't caught up.
+     *
+     * Pass an explicit `validation: { requests: 'off', responses: 'off' }` to
+     * override the dev-mode default. Set `responses: 'warn'` to keep the
+     * logger diagnostic without failing the request — useful while
+     * migrating a handler set from sparse fixtures to spec-compliant
+     * responses. (The logger warning fires in both `'warn'` and `'strict'`
+     * modes; `'strict'` additionally promotes the failure to a
+     * `VALIDATION_ERROR` envelope.)
+     *
+     * Per-side modes:
+     *   - `requests: 'strict'` — reject malformed requests with VALIDATION_ERROR.
+     *     `'warn'` — log a warning, allow the handler to run.
+     *     `'off'` — skip.
+     *   - `responses: 'strict'` — handler-returned drift throws (dev/test canary).
+     *     `'warn'` — log a warning, return the response unchanged.
+     *     `'off'` — skip.
+     *
+     * Cost: one AJV compile per tool on cold start, one validator invocation
+     * per call. The dev-mode default trades that for field-level diagnostics
+     * when handlers drift from the wire contract.
+     */
+    validation?: {
+        requests?: import('../validation/client-hooks').ValidationMode;
+        responses?: import('../validation/client-hooks').ValidationMode;
+    };
+    /**
+     * Register tools outside {@link AdcpToolMap}. Keys are the public tool
+     * names; values follow {@link AdcpCustomToolConfig}.
+     *
+     * Gives sellers a declarative extension point without reaching for the
+     * `getSdkServer()` escape hatch. Typical callers:
+     *
+     *   - AdCP surfaces whose JSON Schemas haven't landed yet
+     *     (`creative_approval`, `update_rights`).
+     *   - Governance specialism helpers (`*_collection_list` family).
+     *   - Test-harness tools (`comply_test_controller` — prefer
+     *     {@link registerTestController} which wraps this).
+     *   - Seller-specific extensions outside the AdCP spec.
+     *
+     * **Custom tools bypass the framework's spec-tool pipeline.** No
+     * idempotency middleware, no governance pre-check, no account
+     * resolution, no response wrapping. The handler receives SDK-validated
+     * args and must return a `CallToolResult`. Call framework helpers
+     * (`checkGovernance`, `adcpError`, `capabilitiesResponse`, …) from
+     * inside the handler if you need those behaviors.
+     *
+     * Name collisions with registered AdcpToolMap tools (from `mediaBuy`,
+     * `signals`, `creative`, `governance`, `accounts`, `eventTracking`,
+     * `sponsoredIntelligence`) or with `get_adcp_capabilities` throw at
+     * construction time — the spec handler wins by convention.
+     */
+    customTools?: Record<string, AdcpCustomToolConfig<any, any>>;
+    /**
+     * Opt-in bridge between the `comply_test_controller` seed store and the
+     * spec-tool pipeline. When `getSeededProducts` is provided, seeded
+     * products flow into `get_products` responses on sandbox requests — the
+     * Group A compliance storyboards rely on this end-to-end flow.
+     * Production traffic (no sandbox marker, or a resolved non-sandbox
+     * account) bypasses the bridge entirely; omit the field in production
+     * configs to be explicit about it.
+     *
+     * See `src/lib/server/test-controller-bridge.ts` for the sandbox-marker
+     * predicate and the merge contract.
+     *
+     * @example
+     * ```ts
+     * import { createAdcpServer, bridgeFromTestControllerStore } from '@adcp/sdk';
+     *
+     * const seedStore = new Map<string, unknown>();
+     * const server = createAdcpServer({
+     *   mediaBuy: { getProducts: handleGetProducts },
+     *   testController: bridgeFromTestControllerStore(seedStore, {
+     *     delivery_type: 'guaranteed',
+     *     channels: ['display'],
+     *   }),
+     * });
+     * ```
+     */
+    testController?: TestControllerBridge<TAccount>;
+}
+/**
+ * Create an AdCP-compliant MCP server from domain-grouped handler functions.
+ *
+ * Before each handler runs, the framework:
+ * 1. Validates the request against the tool's Zod schema (MCP SDK)
+ * 2. Resolves the account (if the tool has an `account` field and `resolveAccount` is configured)
+ *
+ * The handler only runs when all preconditions pass. It receives the validated
+ * params and a context with the resolved account and state store.
+ *
+ * `get_adcp_capabilities` is auto-generated from registered tools.
+ */
+export declare function createAdcpServer<TAccount = unknown>(config: AdcpServerConfig<TAccount>): AdcpServer;
+export {};
+//# sourceMappingURL=create-adcp-server.d.ts.map