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

package/examples/hello_signals_adapter_marketplace.ts

@@ -33,6 +33,8 @@ import {
   type AccountStore,
   type Account,
   type BuyerAgent,
+  type BuyerAgentBillingMode,
+  type BuyerAgentStatus,
   type CachedBuyerAgentRegistry,
 } from '@adcp/sdk/server';
 import type { GetSignalsResponse, ActivateSignalRequest, ActivateSignalSuccess } from '@adcp/sdk/types';
@@ -283,6 +285,114 @@ const ONBOARDING_LEDGER = new Map<string, BuyerAgent>([
   ],
 ]);
 
+const SEEDED_BUYER_AGENT_OVERLAY = new Map<string, BuyerAgent>();
+
+const BUYER_AGENT_BILLING_MODES = new Set<BuyerAgentBillingMode>(['operator', 'agent', 'advertiser']);
+const BUYER_AGENT_STATUSES = new Set<BuyerAgentStatus>(['active', 'suspended', 'blocked']);
+
+function readRequestAccountRef(input: Record<string, unknown> | undefined): Record<string, unknown> | undefined {
+  const topLevel = input?.['account'];
+  if (topLevel != null && typeof topLevel === 'object') return topLevel as Record<string, unknown>;
+  const context = input?.['context'];
+  if (context != null && typeof context === 'object') {
+    const contextAccount = (context as { account?: unknown }).account;
+    if (contextAccount != null && typeof contextAccount === 'object') return contextAccount as Record<string, unknown>;
+  }
+  return undefined;
+}
+
+function readSessionId(input: Record<string, unknown> | undefined): string | undefined {
+  const context = input?.['context'];
+  if (context == null || typeof context !== 'object') return undefined;
+  const sessionId = (context as { session_id?: unknown }).session_id;
+  return typeof sessionId === 'string' && sessionId.length > 0 ? sessionId : undefined;
+}
+
+function accountScope(ref: Record<string, unknown> | undefined): string | undefined {
+  if (!ref) return undefined;
+  const accountId = ref['account_id'];
+  if (typeof accountId === 'string' && accountId.length > 0) return `account_id:${accountId}`;
+  const brand = ref['brand'];
+  const brandDomain = brand != null && typeof brand === 'object' ? (brand as { domain?: unknown }).domain : undefined;
+  const operator = ref['operator'];
+  const sandbox = ref['sandbox'];
+  if (typeof brandDomain !== 'string' && typeof operator !== 'string' && typeof sandbox !== 'boolean') {
+    return undefined;
+  }
+  return JSON.stringify({
+    ...(typeof brandDomain === 'string' && { brand_domain: brandDomain }),
+    ...(typeof operator === 'string' && { operator }),
+    ...(typeof sandbox === 'boolean' && { sandbox }),
+  });
+}
+
+function buyerAgentOverlayKey(
+  agentUrl: string,
+  input: Record<string, unknown> | undefined,
+  ref: Record<string, unknown> | undefined
+): string | undefined {
+  const parts: string[] = [];
+  const sessionId = readSessionId(input);
+  if (sessionId) parts.push(`session:${sessionId}`);
+  const scope = accountScope(ref);
+  if (scope) parts.push(`account:${scope}`);
+  return parts.length > 0 ? `${parts.join('|')}:agent:${agentUrl}` : undefined;
+}
+
+function overlayBuyerAgent(
+  base: BuyerAgent,
+  input: Record<string, unknown> | undefined,
+  ref: Record<string, unknown> | undefined
+): BuyerAgent {
+  const key = buyerAgentOverlayKey(base.agent_url, input, ref);
+  const seeded = key ? SEEDED_BUYER_AGENT_OVERLAY.get(key) : undefined;
+  if (!seeded) {
+    return base;
+  }
+  return {
+    ...base,
+    ...seeded,
+    billing_capabilities: new Set(seeded.billing_capabilities),
+  };
+}
+
+function seedBuyerAgentOverlay(
+  params: {
+    agent_url: string;
+    display_name?: string;
+    status?: BuyerAgentStatus;
+    billing_capabilities?: BuyerAgentBillingMode[];
+    sandbox_only?: boolean;
+  },
+  input: Record<string, unknown>
+): void {
+  const existing =
+    Array.from(ONBOARDING_LEDGER.values()).find(agent => agent.agent_url === params.agent_url) ??
+    Array.from(SEEDED_BUYER_AGENT_OVERLAY.values()).find(agent => agent.agent_url === params.agent_url);
+  const key = buyerAgentOverlayKey(params.agent_url, input, readRequestAccountRef(input));
+  if (!key) {
+    throw new AdcpError('INVALID_REQUEST', {
+      message: 'seed_buyer_agent requires a session_id or account scope for this example overlay.',
+    });
+  }
+  const modes = (params.billing_capabilities ?? Array.from(existing?.billing_capabilities ?? ['operator'])).filter(
+    (mode): mode is BuyerAgentBillingMode => BUYER_AGENT_BILLING_MODES.has(mode as BuyerAgentBillingMode)
+  );
+  const status =
+    params.status && BUYER_AGENT_STATUSES.has(params.status) ? params.status : (existing?.status ?? 'active');
+
+  SEEDED_BUYER_AGENT_OVERLAY.set(key, {
+    agent_url: params.agent_url,
+    display_name: params.display_name ?? existing?.display_name ?? 'Compliance seeded buyer agent',
+    status,
+    billing_capabilities: new Set(modes.length > 0 ? modes : ['operator']),
+    sandbox_only: params.sandbox_only ?? existing?.sandbox_only ?? true,
+  });
+  // Mutating commercial state must purge cached registry entries; otherwise a
+  // just-suspended test buyer could remain active until the TTL expires.
+  agentRegistry.clear();
+}
+
 /**
  * `bearerOnly` because this example authenticates via `verifyApiKey`.
  * Sellers wiring `verifySignatureAsAuthenticator` swap to `signingOnly`
@@ -293,7 +403,7 @@ const ONBOARDING_LEDGER = new Map<string, BuyerAgent>([
  * onboarding ledger. `invalidate(credential)` purges a stale entry when
  * the seller mutates an agent's record (status flip, etc.).
  */
-const agentRegistry: CachedBuyerAgentRegistry = BuyerAgentRegistry.cached(
+const baseAgentRegistry: CachedBuyerAgentRegistry = BuyerAgentRegistry.cached(
   BuyerAgentRegistry.bearerOnly({
     resolveByCredential: async credential => {
       // bearerOnly receives every credential kind; MUST kind-discriminate
@@ -305,6 +415,16 @@ const agentRegistry: CachedBuyerAgentRegistry = BuyerAgentRegistry.cached(
   { ttlSeconds: 60 }
 );
 
+const agentRegistry: CachedBuyerAgentRegistry = {
+  async resolve(authInfo) {
+    const base = await baseAgentRegistry.resolve(authInfo);
+    if (!base) return base;
+    return overlayBuyerAgent(base, authInfo.input, readRequestAccountRef(authInfo.input));
+  },
+  invalidate: credential => baseAgentRegistry.invalidate(credential),
+  clear: () => baseAgentRegistry.clear(),
+};
+
 // ---------------------------------------------------------------------------
 // AdCP-side adapter — typed against SignalsPlatform.
 // ---------------------------------------------------------------------------
@@ -358,9 +478,12 @@ class SignalMarketplaceAdapter implements DecisioningPlatform<Record<string, nev
    * Buyer-agent registry — framework runs `agentRegistry.resolve(authInfo)`
    * once per request and threads the resolved record through `ctx.agent`
    * to specialism handlers AND to `accounts.resolve` (below). When the
-   * resolved agent's `status` is `suspended` / `blocked`, the framework
-   * rejects the request with PERMISSION_DENIED before invoking any
-   * handler — adopters don't reimplement that gate.
+   * resolved agent's durable `status` is `suspended` / `blocked`, the
+   * framework rejects the request with the AdCP 3.1 `AGENT_SUSPENDED` /
+   * `AGENT_BLOCKED` codes before invoking any handler. The scoped
+   * compliance overlay below mirrors that behavior inside `accounts.resolve`
+   * so `seed_buyer_agent` can vary test-only state without mutating the
+   * process-wide onboarding ledger.
    */
   agentRegistry = agentRegistry;
 
@@ -371,20 +494,61 @@ class SignalMarketplaceAdapter implements DecisioningPlatform<Record<string, nev
      *  tenant resolution against the durable buyer-agent identity here
      *  rather than re-deriving from the credential. */
     resolve: async (ref, ctx) => {
-      if (!ref) return null;
+      let effectiveRef = ref;
+      if (!effectiveRef) {
+        const inputAccount = readRequestAccountRef(ctx?.input as Record<string, unknown> | undefined);
+        // TEST-ONLY: comply_test_controller discovery and account-less
+        // controller calls resolve through this auth-derived path. When the
+        // caller supplied an account in the controller payload/context, use
+        // it; otherwise fall back to the single operator this worked example
+        // uses for the conformance harness. Production sellers replace this
+        // with a real principal → sandbox-account lookup.
+        if (inputAccount != null && 'account_id' in inputAccount) return null;
+        const inputBrand = inputAccount?.['brand'];
+        const inputBrandDomain =
+          inputBrand != null && typeof inputBrand === 'object'
+            ? (inputBrand as { domain?: unknown }).domain
+            : undefined;
+        const inputOperator = inputAccount?.['operator'];
+        const inputSandbox = inputAccount?.['sandbox'];
+        effectiveRef =
+          typeof inputOperator === 'string'
+            ? {
+                brand: { domain: typeof inputBrandDomain === 'string' ? inputBrandDomain : 'acmeoutdoor.example' },
+                operator: inputOperator,
+                ...(typeof inputSandbox === 'boolean' && { sandbox: inputSandbox }),
+              }
+            : {
+                brand: { domain: 'acmeoutdoor.example' },
+                operator: 'pinnacle-agency.example',
+                sandbox: true,
+              };
+      }
+      if (!effectiveRef) return null;
       // AccountReference discriminated union: `{ account_id }` post-sync,
       // or `{ brand, operator, sandbox? }` on initial discovery. Mock has
       // no account_id index; SWAP: production keeps an account_id →
       // operator_id index populated during list_accounts.
-      if ('account_id' in ref) return null;
-      const adcpOperator = ref.operator;
+      if ('account_id' in effectiveRef) return null;
+      const adcpOperator = effectiveRef.operator;
       if (!adcpOperator) return null;
       // Optional: gate the operator on the buyer agent's allowed_brands /
       // billing_capabilities. Sellers who don't cross-check operator vs.
       // agent here let any onboarded agent operate on any operator —
       // legitimate for some marketplaces, a leak for others.
-      const buyerAgent = ctx?.agent;
-      void buyerAgent; // demonstration site — wire your own checks here.
+      const buyerAgent =
+        ctx?.agent && ctx.input
+          ? overlayBuyerAgent(ctx.agent, ctx.input, effectiveRef as Record<string, unknown>)
+          : ctx?.agent;
+      if (buyerAgent?.status === 'suspended' || buyerAgent?.status === 'blocked') {
+        throw new AdcpError(buyerAgent.status === 'suspended' ? 'AGENT_SUSPENDED' : 'AGENT_BLOCKED', {
+          message:
+            buyerAgent.status === 'suspended'
+              ? 'Buyer agent is suspended. Contact the seller to restore access.'
+              : 'Buyer agent is blocked.',
+          recovery: 'terminal',
+        });
+      }
       const operatorId = await upstream.lookupOperator(adcpOperator);
       if (!operatorId) return null;
       return {
@@ -392,6 +556,7 @@ class SignalMarketplaceAdapter implements DecisioningPlatform<Record<string, nev
         name: adcpOperator,
         status: 'active',
         operator: adcpOperator,
+        mode: 'sandbox',
         ctx_metadata: { operator_id: operatorId },
         // The upstream here is the AdCP mock-server. Every account it
         // returns is a sandbox account by definition. Production
@@ -540,6 +705,16 @@ serve(
       // account's `mode` is `'sandbox'` or `'mock'` (per `Account.mode`,
       // AdCP 6.7+). See `docs/proposals/lifecycle-state-and-sandbox-authority.md`.
       complyTest: {
+        seed: {
+          // Test-only commercial-state setup for AdCP 3.1 storyboards that
+          // declare `fixtures.buyer_agents[]`. This overlays the static
+          // onboarding ledger by agent_url, so the existing bearer credential
+          // still authenticates normally while the storyboard can vary status,
+          // sandbox_only, or billing_capabilities for the resolved buyer agent.
+          buyer_agent: (params, ctx) => {
+            seedBuyerAgentOverlay(params, ctx.input);
+          },
+        },
         // Adapter resolves principal from auth context. The same string
         // MUST be returned by both record-time (runWithPrincipal) and
         // query-time — mismatch returns zero per cross-tenant isolation.

package/examples/proxy-seller-snap/README.md

@@ -0,0 +1,47 @@
+# Proxy Seller Snap Example
+
+This is the fork target for a seller whose AdCP read path proxies an upstream ads platform: Snap, Meta, TikTok, Pinterest, LinkedIn, Google, Amazon, Reddit, Spotify, Criteo, CitrusAd, FlashTalking, UniversalAds, and similar DSP or walled-garden adapters.
+
+## Diagnostic
+
+If `get_products`, `list_creatives`, `list_property_lists`, or another read tool calls the upstream platform API directly, `comply_test_controller.seed_product` and `seed_creative` are otherwise dead writes. The seed lands in your local test controller, but your read handler asks Snap for products or creatives and never sees it.
+
+Wire `TestControllerBridge` for storyboard conformance. The handler still runs first; the SDK merges seeded fixtures into sandbox responses after the upstream call succeeds. That proves AdCP wire conformance, not live Snap adapter health.
+
+## What This Example Wires
+
+- `TestControllerBridge<SnapAccount>` through `bridgeFromSessionStore`.
+- Resolved-account session loading: `loadSession: (_input, ctx) => sessionStore.loadForAccount(ctx.account)`.
+- Seed selectors for `get_products`, `list_creatives`, and property-list governance reads.
+- `resolveAccount` as the trust boundary. The bridge keys on the resolved `ctx.account`, not on caller-supplied request fields.
+- Optional `comply_test_controller` registration gated by `ADCP_SANDBOX=1`.
+
+## Verification Scope
+
+Bridge-augmented storyboard passes are wire-conformance evidence. They do not prove your Snap OAuth token, account lookup, product catalog, or creative library calls are healthy. Pair this with a live-OAuth sandbox runner that disables or records bridge participation and asserts real upstream traffic.
+
+Run:
+
+```bash
+ADCP_SANDBOX=1 npx tsx examples/proxy-seller-snap/index.ts
+```
+
+Then seed and read with a sandbox account:
+
+```bash
+adcp call http://127.0.0.1:3018/mcp comply_test_controller \
+  '{"scenario":"seed_product","params":{"product_id":"snap-storyboard-product","fixture":{"name":"Seeded product"}},"account":{"account_id":"snap_sandbox_acme","sandbox":true}}' \
+  --auth sk_snap_proxy_harness_do_not_use_in_prod
+
+adcp call http://127.0.0.1:3018/mcp get_products \
+  '{"buying_mode":"brief","brief":"outdoor apparel","account":{"account_id":"snap_sandbox_acme","sandbox":true}}' \
+  --auth sk_snap_proxy_harness_do_not_use_in_prod
+```
+
+Forking checklist:
+
+1. Replace `emptySnapClient` with real Snap OAuth and Marketing API calls.
+2. Replace `resolveSnapAccount` with your production account resolver.
+3. Keep bridge registration limited to sandbox or conformance deployments.
+4. Keep bridge session reads keyed on the resolved account.
+5. Add a live-OAuth test that exercises the adapter without relying on `_bridge`-augmented fixtures.

package/examples/proxy-seller-snap/index.ts

@@ -0,0 +1,321 @@
+/**
+ * proxy-seller-snap — fork target for proxy-shaped sellers whose AdCP read
+ * path fronts an upstream ads platform instead of a seller-owned datastore.
+ *
+ * Snap is the concrete shape because it is representative: account resolution
+ * maps the buyer's AdCP account to a Snap ad account, read handlers call a
+ * Snap-shaped client, and `TestControllerBridge` makes storyboard-seeded
+ * fixtures visible on sandbox reads without pretending the adapter's live
+ * upstream path is healthy.
+ *
+ * FORK CHECKLIST
+ *   1. Replace `emptySnapClient` with your real upstream OAuth/API client.
+ *   2. Replace `resolveSnapAccount` with your production account resolver.
+ *   3. Keep `bridgeFromSessionStore` keyed on resolved `ctx.account`.
+ *   4. Register `comply_test_controller` only in sandbox/conformance hosts.
+ *   5. Add a live-OAuth sandbox runner that proves adapter health without
+ *      relying on `_bridge`-augmented fixtures.
+ *
+ * Run locally:
+ *
+ *   ADCP_SANDBOX=1 npx tsx examples/proxy-seller-snap/index.ts
+ *   adcp call http://127.0.0.1:3018/mcp get_products \
+ *     '{"buying_mode":"brief","brief":"outdoor apparel","account":{"account_id":"snap_sandbox_acme","sandbox":true}}' \
+ *     --auth sk_snap_proxy_harness_do_not_use_in_prod
+ */
+
+import { z } from 'zod';
+import { createAdcpServer } from '@adcp/sdk/server/legacy/v5';
+import {
+  AdcpError,
+  bridgeFromSessionStore,
+  InMemoryStateStore,
+  serve,
+  verifyApiKey,
+  type SeededCreative,
+  type TestControllerBridge,
+} from '@adcp/sdk/server';
+import { createComplyController } from '@adcp/sdk/testing';
+import type { AccountReference, GetProductsResponse, PropertyList } from '@adcp/sdk/types';
+
+type ValidationMode = 'strict' | 'warn' | 'off';
+type Product = NonNullable<GetProductsResponse['products']>[number];
+
+const PORT = Number(process.env['PORT'] ?? 3018);
+const ADCP_AUTH_TOKEN = process.env['ADCP_AUTH_TOKEN'] ?? 'sk_snap_proxy_harness_do_not_use_in_prod';
+const PUBLIC_AGENT_URL = process.env['PUBLIC_AGENT_URL'] ?? `http://127.0.0.1:${PORT}`;
+const DEFAULT_SANDBOX_ACCOUNT_ID = 'snap_sandbox_acme';
+
+interface SnapAccount {
+  id: string;
+  name: string;
+  status: 'active' | 'pending_approval' | 'rejected' | 'payment_required' | 'suspended' | 'closed';
+  sandbox?: boolean;
+  mode?: 'sandbox' | 'live';
+  brand?: { domain: string };
+  operator?: string;
+  ctx_metadata: {
+    snap_ad_account_id: string;
+    bridge_session_id: string;
+  };
+}
+
+interface SnapBridgeSession {
+  seededProducts: Map<string, Record<string, unknown>>;
+  seededCreatives: SeededCreative[];
+  seededPropertyLists: PropertyList[];
+}
+
+export interface SnapClient {
+  listProducts(adAccountId: string): Promise<Product[]>;
+  listCreatives(adAccountId: string): Promise<SeededCreative[]>;
+  listPropertyLists(adAccountId: string): Promise<PropertyList[]>;
+}
+
+export class InMemorySnapSessionStore {
+  private readonly sessions = new Map<string, SnapBridgeSession>();
+
+  loadForAccount(account: SnapAccount): SnapBridgeSession {
+    return this.load(account.ctx_metadata.bridge_session_id);
+  }
+
+  load(sessionId: string): SnapBridgeSession {
+    let session = this.sessions.get(sessionId);
+    if (!session) {
+      session = { seededProducts: new Map(), seededCreatives: [], seededPropertyLists: [] };
+      this.sessions.set(sessionId, session);
+    }
+    return session;
+  }
+
+  loadForControllerInput(input: Record<string, unknown>): SnapBridgeSession {
+    const accountId = readAccountId(input) ?? DEFAULT_SANDBOX_ACCOUNT_ID;
+    return this.load(`snap:${accountId}`);
+  }
+}
+
+export function createInMemorySnapSessionStore(): InMemorySnapSessionStore {
+  return new InMemorySnapSessionStore();
+}
+
+const emptySnapClient: SnapClient = {
+  // SWAP: production calls Snap Marketing API product/catalog endpoints.
+  async listProducts() {
+    return [];
+  },
+  // SWAP: production calls Snap creative library endpoints.
+  async listCreatives() {
+    return [];
+  },
+  // SWAP: production calls the upstream governance/list surface you proxy.
+  async listPropertyLists() {
+    return [];
+  },
+};
+
+// SWAP: production resolves the buyer principal + AccountReference through
+// your account directory or upstream OAuth `/me/adaccounts` equivalent.
+function resolveSnapAccount(ref: AccountReference): SnapAccount | null {
+  if ('account_id' in ref) {
+    if (!ref.account_id) return null;
+    const sandbox = ref.account_id.startsWith('snap_sandbox_');
+    return {
+      id: ref.account_id,
+      name: sandbox ? 'Snap sandbox advertiser' : 'Snap advertiser',
+      status: 'active',
+      sandbox,
+      mode: sandbox ? 'sandbox' : 'live',
+      ctx_metadata: {
+        snap_ad_account_id: ref.account_id.replace(/^snap_/, ''),
+        bridge_session_id: `snap:${ref.account_id}`,
+      },
+    };
+  }
+
+  const domain = ref.brand.domain;
+  if (!domain) return null;
+  const sandbox = domain.endsWith('.sandbox');
+  return {
+    id: sandbox ? DEFAULT_SANDBOX_ACCOUNT_ID : `snap_${domain.replace(/[^a-z0-9]+/gi, '_').toLowerCase()}`,
+    name: `Snap advertiser for ${domain}`,
+    status: 'active',
+    sandbox,
+    mode: sandbox ? 'sandbox' : 'live',
+    brand: { domain },
+    ...(ref.operator !== undefined && { operator: ref.operator }),
+    ctx_metadata: {
+      snap_ad_account_id: sandbox ? 'sandbox_acme' : domain,
+      bridge_session_id: `snap:${sandbox ? DEFAULT_SANDBOX_ACCOUNT_ID : domain}`,
+    },
+  };
+}
+
+function requireResolvedAccount(account: SnapAccount | undefined): SnapAccount {
+  if (!account) {
+    throw new Error('TestControllerBridge requires resolveAccount; no resolved Snap account was available');
+  }
+  return account;
+}
+
+function readAccountId(input: Record<string, unknown>): string | undefined {
+  const account = input['account'];
+  if (!account || typeof account !== 'object') return undefined;
+  const accountId = (account as { account_id?: unknown }).account_id;
+  return typeof accountId === 'string' && accountId.length > 0 ? accountId : undefined;
+}
+
+function makeSnapBridge(sessionStore: InMemorySnapSessionStore): TestControllerBridge<SnapAccount> {
+  return bridgeFromSessionStore<SnapBridgeSession, SnapAccount>({
+    loadSession: (_input, ctx) => sessionStore.loadForAccount(requireResolvedAccount(ctx.account)),
+    selectSeededProducts: session => session.seededProducts,
+    selectSeededCreatives: session => session.seededCreatives,
+    selectSeededPropertyLists: session => session.seededPropertyLists,
+    productDefaults: {
+      name: 'Seeded Snap storyboard product',
+      description: 'Storyboard fixture merged by TestControllerBridge for wire conformance.',
+      publisher_properties: [{ publisher_domain: 'snap.com', selection_type: 'all' }],
+      channels: ['social'],
+      delivery_type: 'non_guaranteed',
+      format_ids: [{ agent_url: PUBLIC_AGENT_URL, id: 'snap-single-image' }],
+      pricing_options: [
+        {
+          pricing_option_id: 'snap-cpm-floor',
+          pricing_model: 'cpm',
+          currency: 'USD',
+          floor_price: 5,
+        },
+      ],
+      reporting_capabilities: {
+        available_reporting_frequencies: ['daily'],
+        expected_delay_minutes: 60,
+        timezone: 'UTC',
+        supports_webhooks: false,
+        available_metrics: ['impressions', 'clicks', 'spend'],
+        date_range_support: 'date_range',
+      },
+    },
+  });
+}
+
+export interface CreateProxySellerSnapServerOptions {
+  snapClient?: SnapClient;
+  sessionStore?: InMemorySnapSessionStore;
+  enableComplyTestController?: boolean;
+  validation?: {
+    requests?: ValidationMode;
+    responses?: ValidationMode;
+  };
+}
+
+export function createProxySellerSnapServer(options: CreateProxySellerSnapServerOptions = {}) {
+  const snapClient = options.snapClient ?? emptySnapClient;
+  const sessionStore = options.sessionStore ?? createInMemorySnapSessionStore();
+
+  const server = createAdcpServer<SnapAccount>({
+    name: 'proxy-seller-snap',
+    version: '1.0.0',
+    stateStore: new InMemoryStateStore(),
+    validation: options.validation ?? { requests: 'warn', responses: 'strict' },
+    resolveAccount: async ref => resolveSnapAccount(ref),
+    resolveSessionKey: ctx => ctx.account?.id ?? 'snap-anonymous',
+    mediaBuy: {
+      getProducts: async (_req, ctx) => ({
+        products: await snapClient.listProducts(requireResolvedAccount(ctx.account).ctx_metadata.snap_ad_account_id),
+        cache_scope: 'account',
+      }),
+    },
+    creative: {
+      listCreatives: async (_req, ctx) => {
+        const creatives = await snapClient.listCreatives(
+          requireResolvedAccount(ctx.account).ctx_metadata.snap_ad_account_id
+        );
+        return {
+          query_summary: { total_matching: creatives.length, returned: creatives.length },
+          pagination: { limit: 50, offset: 0, has_more: false },
+          creatives,
+        };
+      },
+    },
+    governance: {
+      listPropertyLists: async (_req, ctx) => {
+        const lists = await snapClient.listPropertyLists(
+          requireResolvedAccount(ctx.account).ctx_metadata.snap_ad_account_id
+        );
+        return {
+          lists,
+          pagination: { has_more: false },
+        };
+      },
+      getPropertyList: async (req, ctx) => {
+        const lists = await snapClient.listPropertyLists(
+          requireResolvedAccount(ctx.account).ctx_metadata.snap_ad_account_id
+        );
+        const list = lists.find(entry => entry.list_id === req.list_id);
+        if (!list) {
+          throw new AdcpError('REFERENCE_NOT_FOUND', {
+            message: 'Property list not found',
+            field: 'list_id',
+          });
+        }
+        return {
+          list,
+          identifiers: [],
+          pagination: { has_more: false },
+        };
+      },
+    },
+    testController: makeSnapBridge(sessionStore),
+  });
+
+  if (options.enableComplyTestController) {
+    createComplyController({
+      sandboxGate: input =>
+        process.env['ADCP_SANDBOX'] === '1' || readAccountId(input)?.startsWith('snap_sandbox_') === true,
+      inputSchema: {
+        account: z
+          .object({ account_id: z.string().optional(), sandbox: z.boolean().optional() })
+          .passthrough()
+          .optional(),
+      },
+      seed: {
+        product: ({ product_id, fixture }, ctx) => {
+          sessionStore.loadForControllerInput(ctx.input).seededProducts.set(product_id, fixture);
+        },
+        creative: ({ creative_id, fixture }, ctx) => {
+          const session = sessionStore.loadForControllerInput(ctx.input);
+          const withoutExisting = session.seededCreatives.filter(c => c.creative_id !== creative_id);
+          session.seededCreatives = [
+            ...withoutExisting,
+            {
+              creative_id,
+              name: typeof fixture['name'] === 'string' ? fixture['name'] : `Seeded Snap creative ${creative_id}`,
+              format_id: { agent_url: PUBLIC_AGENT_URL, id: 'snap-single-image' },
+              status: readCreativeStatus(fixture['status']),
+              created_date: new Date().toISOString(),
+              updated_date: new Date().toISOString(),
+            } as SeededCreative,
+          ];
+        },
+      },
+    }).register(server);
+  }
+
+  return server;
+}
+
+function readCreativeStatus(value: unknown): SeededCreative['status'] {
+  return value === 'approved' || value === 'pending_review' || value === 'rejected' || value === 'archived'
+    ? value
+    : 'pending_review';
+}
+
+if (require.main === module) {
+  serve(() => createProxySellerSnapServer({ enableComplyTestController: process.env['ADCP_SANDBOX'] === '1' }), {
+    port: PORT,
+    authenticate: verifyApiKey({
+      keys: { [ADCP_AUTH_TOKEN]: { principal: 'snap-proxy-harness' } },
+    }),
+  });
+
+  console.log(`proxy-seller-snap on http://127.0.0.1:${PORT}/mcp`);
+}