@adcp/sdk 5.23.0

package/dist/lib/server/test-controller-bridge.js

@@ -0,0 +1,207 @@
+"use strict";
+/**
+ * Bridge between the `comply_test_controller` seed store and the
+ * `createAdcpServer` spec-tool pipeline.
+ *
+ * Sellers who run the compliance conformance suite seed fixtures via
+ * `comply_test_controller.seed_product`, but those fixtures don't flow into
+ * `get_products` responses unless the seller plumbs it themselves — every
+ * seller ends up rewriting the same "look up seeded products, merge into
+ * handler response, dedupe, sandbox-gate" boilerplate.
+ *
+ * This module exposes a small declarative shape (`TestControllerBridge`)
+ * that the server config accepts; when present, the dispatcher augments
+ * `get_products` responses with seeded products on sandbox requests, and
+ * leaves production traffic untouched.
+ *
+ * The bridge intentionally does NOT know how seeded products are stored.
+ * Sellers provide a `getSeededProducts` callback that returns the list the
+ * SDK should merge — which lets the same wiring work whether the backing
+ * store is in-memory, Postgres, Redis, or a mock.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSandboxRequest = isSandboxRequest;
+exports.mergeSeededProductsIntoResponse = mergeSeededProductsIntoResponse;
+exports.filterValidSeededProducts = filterValidSeededProducts;
+exports.bridgeFromTestControllerStore = bridgeFromTestControllerStore;
+exports.bridgeFromSessionStore = bridgeFromSessionStore;
+const seed_merge_1 = require("../testing/seed-merge");
+/**
+ * Sandbox-request predicate. Reads the spec's two canonical sandbox markers:
+ *
+ *   1. `account.sandbox === true` on the request (per AccountReference
+ *      discriminator — the brand+operator variant carries the flag).
+ *   2. `context.sandbox === true` — storyboards that don't scope through an
+ *      account still flag the envelope so the server can tell them apart.
+ *
+ * Either match is sufficient. Anything else returns `false` and the seeded
+ * fixtures stay hidden. Keep this conservative — a `true` result opts the
+ * request into test-only code paths, so a permissive predicate leaks
+ * fixture data into production.
+ */
+function isSandboxRequest(input) {
+    const account = input.account;
+    if (account && typeof account === 'object' && account.sandbox === true) {
+        return true;
+    }
+    const context = input.context;
+    if (context && typeof context === 'object' && context.sandbox === true) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Merge seeded products into a `get_products` response payload.
+ *
+ * Existing products from the handler come first; seeded entries append
+ * after deduping by `product_id`. On collision, the seeded entry wins so
+ * storyboards that seed to override default inventory see the fixture.
+ *
+ * Returns a NEW response object — the original is not mutated. The
+ * `sandbox: true` flag is stamped on the merged response unless the
+ * handler explicitly declared `sandbox: false` (which stays authoritative
+ * — a handler that has already decided the request is non-sandbox
+ * shouldn't be overridden by the bridge).
+ */
+function mergeSeededProductsIntoResponse(response, seeded) {
+    if (!seeded.length)
+        return response;
+    const seededIds = new Set();
+    for (const p of seeded)
+        seededIds.add(p.product_id);
+    const handlerProducts = Array.isArray(response.products) ? response.products : [];
+    // Keep handler-returned products except those a seeded entry overrides.
+    // A null/undefined product_id on the handler side would be a spec
+    // violation; filtering on `!seededIds.has(id)` preserves it rather than
+    // silently dropping so downstream response validation still catches it.
+    const retained = handlerProducts.filter(p => !seededIds.has(p?.product_id));
+    const merged = {
+        ...response,
+        products: [...retained, ...seeded],
+    };
+    if (response.sandbox !== false) {
+        merged.sandbox = true;
+    }
+    return merged;
+}
+/**
+ * Validate and normalize a list of seeded products returned from a
+ * {@link TestControllerBridge.getSeededProducts} callback. Invalid entries
+ * are dropped with a warning rather than thrown — a broken test fixture
+ * shouldn't tank the request under test. Valid entries pass through as-is.
+ *
+ * An entry is considered valid when it's a plain object with a string
+ * `product_id`. Entries missing `product_id` would collide on
+ * `undefined === undefined` when deduping, so we drop them early.
+ */
+function filterValidSeededProducts(raw, logger) {
+    if (!Array.isArray(raw)) {
+        logger?.warn('testController.getSeededProducts did not return an array; skipping bridge', {
+            received: typeof raw,
+        });
+        return [];
+    }
+    const valid = [];
+    raw.forEach((entry, index) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            logger?.warn('testController.getSeededProducts entry is not an object; dropping', { index });
+            return;
+        }
+        const productId = entry.product_id;
+        if (typeof productId !== 'string' || productId.length === 0) {
+            logger?.warn('testController.getSeededProducts entry missing product_id; dropping', { index });
+            return;
+        }
+        valid.push(entry);
+    });
+    return valid;
+}
+/**
+ * Bridge the default test-controller store (a `Map<string, unknown>` that
+ * holds seeded fixtures by `product_id`, populated by `seed_product` scenarios)
+ * to a {@link TestControllerBridge}.
+ *
+ * Each stored fixture is merged onto `productDefaults` via
+ * {@link mergeSeedProduct} — sellers pass their canonical baseline (delivery
+ * type, channels, reporting capabilities, ...) once here, and the permissive
+ * merge fills in whatever the storyboard fixture didn't declare. The bridge
+ * then returns the resulting `Product[]` for the dispatcher to merge into
+ * `get_products` responses.
+ *
+ * Accepts any `Map<string, unknown>` so it composes with session-scoped
+ * stores as well as the default process-wide one.
+ *
+ * @example
+ * ```ts
+ * const store = new Map<string, unknown>();
+ * const server = createAdcpServer({
+ *   testController: bridgeFromTestControllerStore(store, {
+ *     delivery_type: 'guaranteed',
+ *     channels: ['display'],
+ *   }),
+ * });
+ * ```
+ */
+function bridgeFromTestControllerStore(store, productDefaults = {}) {
+    return {
+        getSeededProducts: () => {
+            const out = [];
+            for (const [productId, fixture] of store.entries()) {
+                const merged = (0, seed_merge_1.mergeSeedProduct)(productDefaults, {
+                    ...(fixture && typeof fixture === 'object' ? fixture : {}),
+                    product_id: productId,
+                });
+                out.push(merged);
+            }
+            return out;
+        },
+    };
+}
+/**
+ * Session-scoped variant of {@link bridgeFromTestControllerStore}.
+ *
+ * {@link bridgeFromTestControllerStore} closes over a single `Map` at
+ * construction time — fine for a process-wide seed store, but doesn't
+ * compose with sellers whose seed state is per-tenant / per-brand / per-
+ * `account_id` and loaded from Postgres or Redis on every request. Those
+ * sellers end up rewriting the same "load session, pull the seed Map,
+ * merge into products" glue each time.
+ *
+ * Sandbox gating and dedup happen in the dispatcher (same path as the
+ * default-store bridge); this helper returns fixtures unconditionally
+ * and leaves scoping to the framework.
+ *
+ * @example
+ * ```ts
+ * import { bridgeFromSessionStore } from '@adcp/sdk/server';
+ *
+ * const server = createAdcpServer({
+ *   testController: bridgeFromSessionStore({
+ *     loadSession: (input) => loadComplySession(sessionKeyFromInput(input)),
+ *     selectSeededProducts: (session) => session.complyExtensions.seededProducts,
+ *     productDefaults: SEED_PRODUCT_DEFAULTS,
+ *   }),
+ * });
+ * ```
+ */
+function bridgeFromSessionStore(opts) {
+    const { loadSession, selectSeededProducts, productDefaults = {} } = opts;
+    return {
+        getSeededProducts: async (ctx) => {
+            const session = await loadSession(ctx.input);
+            const entries = await selectSeededProducts(session);
+            if (!entries)
+                return [];
+            const out = [];
+            for (const [productId, fixture] of entries) {
+                const merged = (0, seed_merge_1.mergeSeedProduct)(productDefaults, {
+                    ...(fixture && typeof fixture === 'object' ? fixture : {}),
+                    product_id: productId,
+                });
+                out.push(merged);
+            }
+            return out;
+        },
+    };
+}
+//# sourceMappingURL=test-controller-bridge.js.map

package/dist/lib/server/test-controller-bridge.js.map

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

package/dist/lib/server/test-controller.d.ts

@@ -0,0 +1,388 @@
+/**
+ * Server-side comply_test_controller implementation.
+ *
+ * Most new code should use {@link createComplyController} from
+ * `@adcp/sdk/testing` — it wraps this module with a domain-grouped
+ * (`seed` / `force` / `simulate`) adapter surface, typed params, sandbox
+ * gating, and built-in seed idempotency. The functions below remain
+ * supported for existing integrations and for custom wrappers that need
+ * access to the underlying request handler / MCP envelope helpers.
+ *
+ * Sellers typically call `registerTestController(server, store)` to add the
+ * `comply_test_controller` tool to their MCP server. The TestControllerStore
+ * interface lets sellers wire up their own state management while the SDK
+ * handles request parsing, scenario dispatch, and response formatting.
+ *
+ * @example Basic usage — single in-memory store
+ * ```typescript
+ * import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+ * import { registerTestController, TestControllerError } from '@adcp/sdk';
+ *
+ * const accounts = new Map<string, string>();
+ *
+ * registerTestController(server, {
+ *   async forceAccountStatus(accountId, status) {
+ *     const prev = accounts.get(accountId);
+ *     if (!prev) throw new TestControllerError('NOT_FOUND', `Account ${accountId} not found`);
+ *     accounts.set(accountId, status);
+ *     return { success: true, previous_state: prev, current_state: status };
+ *   },
+ * });
+ * ```
+ *
+ * @example Session-backed store (factory shape)
+ *
+ * If your session state is persisted (Postgres/Redis/JSONB) and rehydrated into
+ * a *new* object per request, closures over module-level state will silently
+ * lose data between calls. Pass a factory object: `scenarios` declares the
+ * static capability set (answered without invoking your factory), and
+ * `createStore` runs per request so the returned store closes over the live
+ * session.
+ *
+ * ```typescript
+ * import { registerTestController, CONTROLLER_SCENARIOS, enforceMapCap } from '@adcp/sdk';
+ *
+ * registerTestController(server, {
+ *   scenarios: [CONTROLLER_SCENARIOS.FORCE_ACCOUNT_STATUS, CONTROLLER_SCENARIOS.FORCE_MEDIA_BUY_STATUS],
+ *   async createStore(input) {
+ *     const session = await loadSession((input.context as { session_id?: string })?.session_id);
+ *     return {
+ *       async forceAccountStatus(accountId, status) {
+ *         enforceMapCap(session.accountStatuses, accountId, 'account statuses');
+ *         const prev = session.accountStatuses.get(accountId) ?? 'active';
+ *         session.accountStatuses.set(accountId, status);
+ *         await saveSession(session);
+ *         return { success: true, previous_state: prev, current_state: status };
+ *       },
+ *     };
+ *   },
+ * });
+ * ```
+ *
+ * @example Custom MCP wrapper
+ *
+ * For wrappers that need `AsyncLocalStorage`, sandbox gating, or a custom task
+ * store, bypass `registerTestController` and compose the exported building
+ * blocks directly. `TOOL_INPUT_SHAPE` is the canonical Zod shape;
+ * `toMcpResponse` produces the same envelope the default registration does.
+ *
+ * ```typescript
+ * import { AsyncLocalStorage } from 'node:async_hooks';
+ * import {
+ *   handleTestControllerRequest,
+ *   toMcpResponse,
+ *   TOOL_INPUT_SHAPE,
+ * } from '@adcp/sdk';
+ *
+ * const sessionContext = new AsyncLocalStorage<{ sessionId: string }>();
+ * const store = { async forceAccountStatus() { ... } };
+ *
+ * server.registerTool(
+ *   'comply_test_controller',
+ *   { description: 'Sandbox only.', inputSchema: TOOL_INPUT_SHAPE },
+ *   async input => {
+ *     if (!sandboxEnabled()) {
+ *       return toMcpResponse({ success: false, error: 'FORBIDDEN', error_detail: 'Sandbox disabled' });
+ *     }
+ *     return sessionContext.run({ sessionId: (input.context as { session_id: string }).session_id }, async () => {
+ *       const response = await handleTestControllerRequest(store, input as Record<string, unknown>);
+ *       return toMcpResponse(response);
+ *     });
+ *   }
+ * );
+ * ```
+ */
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { AdcpServer } from './adcp-server';
+import type { ListScenariosSuccess, StateTransitionSuccess, SimulationSuccess, ForcedDirectiveSuccess, ControllerError, ComplyTestControllerResponse } from '../types/tools.generated';
+import type { AccountStatus, MediaBuyStatus, CreativeStatus } from '../types/core.generated';
+import type { McpToolResponse } from './responses';
+/** Scenario names advertised via `list_scenarios` (force_* and simulate_*).
+ * Seed scenarios are NOT advertised — the spec treats them as universal
+ * request-time capabilities, not a discoverable subset. The upstream
+ * `ListScenariosSuccess['scenarios']` union includes seeds (open-for-
+ * extension), so we explicitly subtract them here. */
+export type ControllerScenario = Exclude<ListScenariosSuccess['scenarios'][number], SeedScenario>;
+/** Scenario names accepted in `scenario` requests but not advertised via
+ * `list_scenarios`. Sellers opt in by implementing the matching store method. */
+export type SeedScenario = 'seed_product' | 'seed_pricing_option' | 'seed_creative' | 'seed_plan' | 'seed_media_buy' | 'seed_creative_format';
+/**
+ * Scenario name constants for force_* and simulate_* (the advertised set).
+ * Use in place of string literals for type-safe dispatch in custom wrappers,
+ * tests, and factory `scenarios` declarations.
+ *
+ * ```ts
+ * if (input.scenario === CONTROLLER_SCENARIOS.FORCE_ACCOUNT_STATUS) { ... }
+ * ```
+ */
+export declare const CONTROLLER_SCENARIOS: {
+    readonly FORCE_CREATIVE_STATUS: "force_creative_status";
+    readonly FORCE_ACCOUNT_STATUS: "force_account_status";
+    readonly FORCE_MEDIA_BUY_STATUS: "force_media_buy_status";
+    readonly FORCE_SESSION_STATUS: "force_session_status";
+    readonly FORCE_CREATE_MEDIA_BUY_ARM: "force_create_media_buy_arm";
+    readonly FORCE_TASK_COMPLETION: "force_task_completion";
+    readonly SIMULATE_DELIVERY: "simulate_delivery";
+    readonly SIMULATE_BUDGET_SPEND: "simulate_budget_spend";
+};
+/**
+ * Seed scenario name constants. Used by seed dispatch and the
+ * {@link createComplyController} domain-grouped façade. Seeds are not
+ * advertised via `list_scenarios`.
+ */
+export declare const SEED_SCENARIOS: {
+    readonly SEED_PRODUCT: "seed_product";
+    readonly SEED_PRICING_OPTION: "seed_pricing_option";
+    readonly SEED_CREATIVE: "seed_creative";
+    readonly SEED_PLAN: "seed_plan";
+    readonly SEED_MEDIA_BUY: "seed_media_buy";
+    readonly SEED_CREATIVE_FORMAT: "seed_creative_format";
+};
+/**
+ * Stable `SeedSuccess.message` strings the SDK's `dispatchSeed` emits.
+ * Adopters who want to detect first-seed vs idempotent-replay can match
+ * on these constants instead of grepping for the literal prose.
+ *
+ * Third-party sellers MAY emit any string the spec allows (the spec only
+ * requires `success: true`); these constants are SDK-specific contracts
+ * and not portable across implementations. For cross-implementation
+ * replay detection, do not rely on `message`.
+ */
+export declare const SEED_MESSAGES: {
+    readonly fresh: "Fixture seeded";
+    readonly replay: "Fixture re-seeded (equivalent)";
+};
+/**
+ * Seller-side store for comply_test_controller.
+ *
+ * Implement the methods for each scenario you support.
+ * Unimplemented methods mean that scenario is not advertised in list_scenarios.
+ */
+export interface TestControllerStore {
+    /** Transition a creative to the specified status. */
+    forceCreativeStatus?(creativeId: string, status: CreativeStatus, rejectionReason?: string): Promise<StateTransitionSuccess>;
+    /** Transition an account to the specified status. */
+    forceAccountStatus?(accountId: string, status: AccountStatus): Promise<StateTransitionSuccess>;
+    /** Transition a media buy to the specified status. */
+    forceMediaBuyStatus?(mediaBuyId: string, status: MediaBuyStatus, rejectionReason?: string): Promise<StateTransitionSuccess>;
+    /** Transition an SI session to a terminal status. */
+    forceSessionStatus?(sessionId: string, status: 'complete' | 'terminated', terminationReason?: string): Promise<StateTransitionSuccess>;
+    /**
+     * Register a directive shaping the next `create_media_buy` call from this
+     * authenticated sandbox account into the requested arm. The directive is
+     * consumed on the next call. `arm: 'submitted'` requires `task_id` so the
+     * seller's task envelope is deterministic (the buyer can drive
+     * `tasks/get` with the registered id).
+     */
+    forceCreateMediaBuyArm?(params: {
+        arm: 'submitted' | 'input-required';
+        task_id?: string;
+        message?: string;
+    }): Promise<ForcedDirectiveSuccess>;
+    /**
+     * Transition an in-flight task to `completed` and record the supplied
+     * completion payload. The seller MUST deliver `result` verbatim to the
+     * buyer's `push_notification_config.url` per the AdCP 3.0 completion path.
+     */
+    forceTaskCompletion?(taskId: string, result: Record<string, unknown>): Promise<StateTransitionSuccess>;
+    /** Inject synthetic delivery data for a media buy. */
+    simulateDelivery?(mediaBuyId: string, params: {
+        impressions?: number;
+        clicks?: number;
+        reported_spend?: {
+            amount: number;
+            currency: string;
+        };
+        conversions?: number;
+    }): Promise<SimulationSuccess>;
+    /** Simulate budget consumption to a specified percentage. */
+    simulateBudgetSpend?(params: {
+        account_id?: string;
+        media_buy_id?: string;
+        spend_percentage: number;
+    }): Promise<SimulationSuccess>;
+    /** Seed a product fixture. Returns when the fixture is persisted. */
+    seedProduct?(productId: string, fixture: Record<string, unknown> | undefined): Promise<void>;
+    /** Seed a pricing option fixture (scoped to a product). */
+    seedPricingOption?(productId: string, pricingOptionId: string, fixture: Record<string, unknown> | undefined): Promise<void>;
+    /** Seed a creative fixture. */
+    seedCreative?(creativeId: string, fixture: Record<string, unknown> | undefined): Promise<void>;
+    /** Seed a plan fixture. */
+    seedPlan?(planId: string, fixture: Record<string, unknown> | undefined): Promise<void>;
+    /** Seed a media-buy fixture. */
+    seedMediaBuy?(mediaBuyId: string, fixture: Record<string, unknown> | undefined): Promise<void>;
+    /**
+     * Seed a creative-format fixture. The seller MUST expose this format ID
+     * in `list_creative_formats` responses for the duration of the compliance
+     * session.
+     */
+    seedCreativeFormat?(formatId: string, fixture: Record<string, unknown> | undefined): Promise<void>;
+}
+/**
+ * Factory shape for per-request stores. `scenarios` answers list_scenarios
+ * without invoking `createStore`, so session-backed factories never run on
+ * capability-discovery pings. `createStore` runs once per non-`list_scenarios`
+ * request and returns a store bound to the current session.
+ */
+export interface TestControllerStoreFactory {
+    /**
+     * Static list of scenarios this factory's stores support. The SDK returns
+     * this verbatim for `list_scenarios` — your `createStore` is skipped on
+     * capability probes, so you don't have to load a session just to answer.
+     */
+    scenarios: readonly ControllerScenario[];
+    /**
+     * Build a {@link TestControllerStore} bound to the current request. Invoked
+     * once per non-`list_scenarios` request with the raw tool input. Throw
+     * {@link TestControllerError} for typed errors (`FORBIDDEN`, `NOT_FOUND`);
+     * other exceptions surface as `INTERNAL_ERROR` with a scrubbed detail.
+     */
+    createStore(input: Record<string, unknown>): TestControllerStore | Promise<TestControllerStore>;
+}
+/** Either a pre-built store (simple case) or a per-request factory (session-backed case). */
+export type TestControllerStoreOrFactory = TestControllerStore | TestControllerStoreFactory;
+/**
+ * Throw from TestControllerStore methods to return a typed controller error.
+ *
+ * @example
+ * ```typescript
+ * throw new TestControllerError('NOT_FOUND', `Account ${id} not found`);
+ * throw new TestControllerError('INVALID_TRANSITION', 'Cannot pause a completed buy', 'completed');
+ * ```
+ */
+export declare class TestControllerError extends Error {
+    readonly code: ControllerError['error'];
+    readonly currentState?: string | null | undefined;
+    constructor(code: ControllerError['error'], message: string, currentState?: string | null | undefined);
+}
+/**
+ * Default cap on the number of entries a single session-scoped Map may hold
+ * before {@link enforceMapCap} rejects further inserts. Tuned for compliance
+ * testing workloads — raise the cap explicitly if you need a higher ceiling.
+ */
+export declare const SESSION_ENTRY_CAP = 1000;
+/**
+ * Reject new entries when `map` has reached `cap`. Use inside
+ * {@link TestControllerStore} methods before `.set()` on any Map that
+ * accumulates per-session state (account statuses, media-buy states,
+ * simulated deliveries). Existing keys are allowed to overwrite — only
+ * *net-new* keys are rejected at the cap.
+ *
+ * Rejects via {@link TestControllerError} with code `INVALID_STATE`, which the
+ * dispatcher converts to a typed `ControllerError` response. The caller gets
+ * a clear "clear the session or reuse an existing id" error rather than silent
+ * LRU eviction that would make compliance tests nondeterministic.
+ *
+ * @param label - Human-readable plural noun used in the error message
+ *   (`"account statuses"`, `"media buy states"`). Intended to be a
+ *   caller-controlled string literal; defensively truncated to 64 chars and
+ *   stripped of non-printable characters before interpolation so user-controlled
+ *   input can't spam logs.
+ *
+ * @example
+ * ```ts
+ * async forceAccountStatus(accountId, status) {
+ *   enforceMapCap(session.accountStatuses, accountId, 'account statuses');
+ *   const prev = session.accountStatuses.get(accountId) ?? 'active';
+ *   session.accountStatuses.set(accountId, status);
+ *   return { success: true, previous_state: prev, current_state: status };
+ * }
+ * ```
+ */
+export declare function enforceMapCap<V>(map: Map<string, V>, key: string, label: string, cap?: number): void;
+/**
+ * Per-controller cache for seed-fixture equivalence checks. The handler uses
+ * it to enforce the spec-level rule that re-seeding with the same ID and an
+ * equivalent fixture yields `SeedSuccess` with `message: "Fixture re-seeded
+ * (equivalent)"`, while a divergent fixture returns `INVALID_PARAMS`.
+ *
+ * Passed explicitly to {@link handleTestControllerRequest} so custom wrappers
+ * can scope the cache to a session, tenant, or test run. Keys are
+ * scenario-scoped (`seed_creative:cr-1`) to avoid cross-kind collisions.
+ */
+export interface SeedFixtureCache {
+    get(key: string): Record<string, unknown> | undefined;
+    set(key: string, fixture: Record<string, unknown>): void;
+    has(key: string): boolean;
+}
+/** Build an in-memory {@link SeedFixtureCache}. Capped at {@link SESSION_ENTRY_CAP}
+ * net-new keys to bound memory from a sandbox-authed caller that keeps seeding
+ * fresh IDs. Existing keys are always writable so re-seeds continue to work at
+ * the cap. Raise the cap explicitly for high-volume test runs. */
+export declare function createSeedFixtureCache(cap?: number): SeedFixtureCache;
+/**
+ * Handle a `comply_test_controller` request. Exported so custom MCP wrappers
+ * can compose it with their own middleware (AsyncLocalStorage, sandbox gating,
+ * logging) without going through {@link registerTestController}.
+ *
+ * `list_scenarios` is answered from the static capability set (store method
+ * presence for plain stores, `factory.scenarios` for factories) and never
+ * invokes `factory.createStore`. Session-backed factories can therefore load
+ * real session state unconditionally.
+ */
+export declare function handleTestControllerRequest(storeOrFactory: TestControllerStoreOrFactory, input: Record<string, unknown>, options?: {
+    seedCache?: SeedFixtureCache;
+}): Promise<ComplyTestControllerResponse>;
+/**
+ * Wrap a {@link ComplyTestControllerResponse} in an MCP tool response envelope
+ * (`content` + `structuredContent` + `isError`). Exported so custom wrappers
+ * can reuse the same summary/error shape as {@link registerTestController}.
+ */
+export declare function toMcpResponse(data: ComplyTestControllerResponse): McpToolResponse & {
+    isError?: true;
+};
+/**
+ * Canonical Zod input schema for the `comply_test_controller` tool. Pass as
+ * the `inputSchema` argument to `server.registerTool(...)` in custom wrappers
+ * so the request shape stays in sync with {@link registerTestController}.
+ *
+ * Matches `ComplyTestControllerRequest` from the generated schema: `scenario`
+ * (required), `params` (scenario-specific), and the universal `context` / `ext`
+ * envelope fields. No top-level `account` — AdCP routes account context
+ * through `context` on this tool.
+ *
+ * **Extending for vendor fields.** Custom wrappers that route sandbox gating
+ * or tenant scoping on top-level fields can extend the shape locally:
+ *
+ * ```ts
+ * const MY_SHAPE = {
+ *   ...TOOL_INPUT_SHAPE,
+ *   account: z.object({ sandbox: z.boolean() }).passthrough().optional(),
+ * };
+ * server.registerTool(
+ *   'comply_test_controller',
+ *   { description: 'Sandbox only.', inputSchema: MY_SHAPE },
+ *   async input => {
+ *     if (input.account?.sandbox !== true) return toMcpResponse({ ... });
+ *     return toMcpResponse(await handleTestControllerRequest(store, input as Record<string, unknown>));
+ *   }
+ * );
+ * ```
+ *
+ * This keeps the default registration protocol-compliant while giving
+ * wrapper authors a documented extension point.
+ */
+export declare const TOOL_INPUT_SHAPE: {
+    scenario: z.ZodString;
+    params: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    ext: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+};
+/**
+ * Register the `comply_test_controller` tool on an MCP server.
+ *
+ * Accepts a plain {@link TestControllerStore} (scenarios inferred from
+ * implemented methods) or a {@link TestControllerStoreFactory} (scenarios
+ * declared explicitly; `createStore` runs per request for session-backed
+ * state). See the module-level examples for both patterns.
+ *
+ * The `server` argument takes either an `AdcpServer` from
+ * `createAdcpServer()` or a raw SDK `McpServer` from
+ * `createTaskCapableServer()` — the helper unwraps the opaque handle
+ * when needed so tool registration reaches the underlying SDK server.
+ */
+export declare function registerTestController(server: AdcpServer | McpServer, storeOrFactory: TestControllerStoreOrFactory, options?: {
+    seedCache?: SeedFixtureCache;
+}): void;
+//# sourceMappingURL=test-controller.d.ts.map

package/dist/lib/server/test-controller.d.ts.map

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