@adcp/sdk 14.0.0-beta.0 → 14.0.0-beta.1

package/dist/lib/server/decisioning/runtime/from-platform.mjs

@@ -1,7 +1,8 @@
 import { randomUUID } from "node:crypto";
 import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
 import {
-  createAdcpServer
+  createAdcpServer,
+  COMPACT_MEDIA_BUY_MUTATION_TOOLS
 } from "../../create-adcp-server.mjs";
 import { normalizeTargetingCapabilities } from "../capabilities.mjs";
 import {
@@ -1025,8 +1026,8 @@ function createAdcpServerFromPlatform(platform, opts) {
   const som = somCandidate != null && somCandidate.length > 0 ? somCandidate : void 0;
   const fc = platform.capabilities.frequency_capping;
   const targeting = platform.capabilities.targeting ? normalizeTargetingCapabilities(platform.capabilities.targeting) : void 0;
-  const hasSalesPlatform = platform.sales != null || platform.proposalManager != null;
-  const supportsProposals = platform.capabilities.supportsProposals ?? (platform.proposalManager != null ? true : hasSalesPlatform ? false : void 0);
+  const hasSalesPlatform = platform.sales != null || platform.mediaBuyLifecycle != null || platform.proposalManager != null;
+  const supportsProposals = platform.capabilities.supportsProposals ?? (platform.proposalManager != null || platform.mediaBuyLifecycle?.requestProposals != null || platform.mediaBuyLifecycle?.refineProposals != null ? true : hasSalesPlatform ? false : void 0);
   const hasMediaBuyProjection = hasSalesPlatform || at != null || ct != null || cs != null || som != null || fc != null || targeting != null || supportsProposals !== void 0;
   const configuredAdcpVersion = opts.adcpVersion ?? ADCP_VERSION;
   const configuredRelease = parseAdcpRelease(configuredAdcpVersion);
@@ -1155,6 +1156,23 @@ function createAdcpServerFromPlatform(platform, opts) {
     }
   };
   const ctxFor = makeCtxFor(effectiveCtxMetadata);
+  const platformProposalNegotiation = buildProposalNegotiationHandlers(
+    platform,
+    taskRegistry,
+    taskWebhookEmit,
+    observability,
+    fwLogger,
+    {
+      allowPrivateWebhookUrls: opts.allowPrivateWebhookUrls === true,
+      autoEmitCompletionWebhooks: opts.autoEmitCompletionWebhooks === true
+    },
+    ctxFor
+  );
+  if (platformProposalNegotiation && opts.proposalNegotiation) {
+    throw new PlatformConfigError(
+      "Configure refine_proposals through platform.mediaBuyLifecycle or opts.proposalNegotiation, not both"
+    );
+  }
   if (opts.resolveIdempotencyPrincipal === void 0) {
     const env = process.env.NODE_ENV;
     const inDevAllowlist = env === "test" || env === "development";
@@ -1167,6 +1185,7 @@ function createAdcpServerFromPlatform(platform, opts) {
   }
   const config = {
     ...opts,
+    requireCompactMutationAccountScope: true,
     taskRegistry,
     ...autoSeedStore != null && { testController: makeAutoSeedBridge(autoSeedStore) },
     ...projectedCapabilitiesConfig != null && { capabilities: projectedCapabilitiesConfig },
@@ -1190,17 +1209,14 @@ function createAdcpServerFromPlatform(platform, opts) {
     // Pool-derived stores override the spread above when adopters supplied
     // `pool` but no explicit per-store opt. Explicit values still win.
     ...effectiveIdempotency !== void 0 && { idempotency: effectiveIdempotency },
-    // v6 default principal resolver: every mutating tool requires an
-    // idempotency principal (the v5 createAdcpServer surface returns
-    // SERVICE_UNAVAILABLE when one isn't wired). v6 platform adopters
-    // who skip the explicit hook get a sensible default — auth client
-    // id when present (multi-tenant: each buyer owns its own
-    // idempotency namespace), else session key, else account id
-    // (single-tenant fallback). Adopters override by passing
-    // resolveIdempotencyPrincipal in opts; the spread above keeps
-    // explicit values winning. Closed by the Emma matrix surfacing
-    // SERVICE_UNAVAILABLE on every v6 mutating call.
-    resolveIdempotencyPrincipal: opts.resolveIdempotencyPrincipal ?? ((ctx) => ctx.authInfo?.clientId ?? ctx.sessionKey ?? ctx.account?.id ?? void 0),
+    // Preserve the SDK 13 principal namespace for established tools so a
+    // retry spanning a rolling 13→14 deployment still finds its durable
+    // idempotency entry. The new compact lifecycle uses credential-kind
+    // namespacing and refuses session/account fallbacks, preventing
+    // cross-credential collisions without reopening a duplicate-buy window
+    // on create_media_buy/update_media_buy. Explicit adopter resolvers still
+    // win for every tool.
+    resolveIdempotencyPrincipal: opts.resolveIdempotencyPrincipal ?? ((ctx, _params, toolName) => COMPACT_MEDIA_BUY_MUTATION_TOOLS.has(toolName) ? authenticatedPrincipalFor(ctx) : ctx.authInfo?.clientId ?? ctx.sessionKey ?? ctx.account?.id ?? void 0),
     resolveAccount: async (ref, ctx) => {
       const start = Date.now();
       let resolved = false;
@@ -1302,6 +1318,7 @@ function createAdcpServerFromPlatform(platform, opts) {
       mergeOpts,
       defaultCreativeWireMode
     ),
+    proposalNegotiation: platformProposalNegotiation ?? opts.proposalNegotiation,
     creative: mergeHandlers(
       legacyHandlers.creative,
       buildCreativeHandlers(
@@ -2101,6 +2118,17 @@ function taskOwnerScopeFor(ctx, accountId) {
   }
   return `account:${accountId}`;
 }
+function authenticatedPrincipalFor(ctx) {
+  if (ctx.agent?.agent_url) return `agent:${ctx.agent.agent_url}`;
+  const credential = ctx.authInfo?.credential;
+  if (credential?.kind === "http_sig") return `http_sig:${credential.agent_url}`;
+  if (credential?.kind === "oauth") return `oauth:${credential.client_id}`;
+  if (credential?.kind === "api_key") return `api_key:${credential.key_id}`;
+  if (typeof ctx.authInfo?.clientId === "string" && ctx.authInfo.clientId.length > 0) {
+    return `client:${ctx.authInfo.clientId}`;
+  }
+  return void 0;
+}
 function hasPushNotificationConfig(params) {
   return params != null && typeof params === "object" && params.push_notification_config !== void 0;
 }
@@ -2763,11 +2791,167 @@ function validatePushNotificationOperationId(operationId) {
   }
   return { ok: true };
 }
+function buildProposalNegotiationHandlers(platform, taskRegistry, taskWebhookEmit, observability, logger, pushOpts, ctxFor) {
+  const lifecycle = platform.mediaBuyLifecycle;
+  if (!lifecycle?.refineProposals) return void 0;
+  if (!lifecycle.proposalRefinement) {
+    throw new PlatformConfigError(
+      "mediaBuyLifecycle.refineProposals requires mediaBuyLifecycle.proposalRefinement capability metadata"
+    );
+  }
+  return {
+    capabilities: lifecycle.proposalRefinement,
+    resolveScope: (ctx) => {
+      const accountId = ctx.account?.id;
+      if (!accountId) {
+        throw new AdcpError("ACCOUNT_NOT_FOUND", {
+          message: "refine_proposals requires an authenticated account scope",
+          recovery: "correctable"
+        });
+      }
+      const principalId = authenticatedPrincipalFor(ctx);
+      if (!principalId) {
+        throw new AdcpError("AUTH_REQUIRED", {
+          message: "refine_proposals requires an authenticated buyer principal",
+          recovery: "correctable"
+        });
+      }
+      return { tenant_id: accountId, account_id: accountId, principal_id: principalId };
+    },
+    refineProposals: async (params, ctx) => {
+      const request = params;
+      const reqCtx = ctxFor(ctx, request);
+      if (!reqCtx.account?.id) {
+        throw new AdcpError("ACCOUNT_NOT_FOUND", {
+          message: "refine_proposals requires an authenticated account scope",
+          recovery: "correctable"
+        });
+      }
+      return projectSync(
+        async () => {
+          const push = extractPushConfig(request, logger, {
+            allowPrivateWebhookUrls: pushOpts.allowPrivateWebhookUrls
+          });
+          const result = await lifecycle.refineProposals(params, reqCtx);
+          return routeIfHandoff(
+            taskRegistry,
+            {
+              tool: "refine_proposals",
+              accountId: reqCtx.account.id,
+              ownerScope: taskOwnerScopeFor(ctx, reqCtx.account.id),
+              pushNotificationUrl: push.url,
+              pushNotificationToken: push.token,
+              pushNotificationOperationId: push.operationId,
+              emitWebhook: taskWebhookEmit ?? ctx.emitWebhook,
+              autoEmitCompletion: pushOpts.autoEmitCompletionWebhooks,
+              observability,
+              logger
+            },
+            result,
+            (value) => value
+          );
+        },
+        (value) => value
+      );
+    }
+  };
+}
 function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observability, logger, pushOpts, ctxFor, ctxMetadataStore, mediaBuyStore, proposalStore, legacyFormatConverter, canonicalFormatLegacyResolver, creativeWireMode) {
   const sales = platform.sales;
+  const lifecycle = platform.mediaBuyLifecycle;
+  const getMediaBuyDelivery = lifecycle?.getMediaBuyDelivery ?? sales?.getMediaBuyDelivery;
+  const getMediaBuys = lifecycle?.getMediaBuys ?? sales?.getMediaBuys;
   const proposalManager = platform.proposalManager;
-  if (!sales && !proposalManager) return void 0;
+  if (!sales && !lifecycle && !proposalManager) return void 0;
+  const dispatchCompactMutation = async (tool, params, ctx, invoke) => {
+    return projectSync(
+      async () => {
+        if (ctx.authInfo === void 0 && ctx.agent === void 0) {
+          throw new AdcpError("AUTH_MISSING", {
+            message: `${tool} requires an authenticated buyer principal`,
+            recovery: "correctable"
+          });
+        }
+        const accountId = ctx.account?.id;
+        if (!accountId) {
+          throw new AdcpError("ACCOUNT_NOT_FOUND", {
+            message: `${tool} requires a resolved account scope`,
+            recovery: "correctable"
+          });
+        }
+        const principalId = authenticatedPrincipalFor(ctx);
+        if (!principalId) {
+          throw new AdcpError("AUTH_MISSING", {
+            message: `${tool} requires an authenticated buyer principal`,
+            recovery: "correctable"
+          });
+        }
+        const callerMutationScope = Object.freeze({
+          tenant_id: accountId,
+          account_id: accountId,
+          principal_id: principalId
+        });
+        const reqCtx = ctxFor({ ...ctx, callerMutationScope }, params);
+        const push = extractPushConfig(params, logger, {
+          allowPrivateWebhookUrls: pushOpts.allowPrivateWebhookUrls
+        });
+        const result = await invoke(reqCtx);
+        return routeIfHandoff(
+          taskRegistry,
+          {
+            tool,
+            accountId,
+            ownerScope: taskOwnerScopeFor(ctx, accountId),
+            pushNotificationUrl: push.url,
+            pushNotificationToken: push.token,
+            pushNotificationOperationId: push.operationId,
+            emitWebhook: taskWebhookEmit ?? ctx.emitWebhook,
+            autoEmitCompletion: pushOpts.autoEmitCompletionWebhooks,
+            observability,
+            logger
+          },
+          result,
+          (value) => value
+        );
+      },
+      (value) => value
+    );
+  };
   return {
+    ...lifecycle?.listProducts && {
+      listProducts: async (...[params, ctx]) => {
+        const reqCtx = ctxFor(ctx, params);
+        return projectSync(
+          () => lifecycle.listProducts(params, reqCtx),
+          (value) => value
+        );
+      }
+    },
+    ...lifecycle?.requestProposals && {
+      requestProposals: async (...[params, ctx]) => dispatchCompactMutation(
+        "request_proposals",
+        params,
+        ctx,
+        (reqCtx) => lifecycle.requestProposals(params, reqCtx)
+      )
+    },
+    ...lifecycle?.declineProposals && {
+      declineProposals: async (...[params, ctx]) => dispatchCompactMutation(
+        "decline_proposals",
+        params,
+        ctx,
+        (reqCtx) => lifecycle.declineProposals(params, reqCtx)
+      )
+    },
+    ...lifecycle?.buyProducts && {
+      buyProducts: async (...[params, ctx]) => dispatchCompactMutation("buy_products", params, ctx, (reqCtx) => lifecycle.buyProducts(params, reqCtx))
+    },
+    ...lifecycle?.acceptProposal && {
+      acceptProposal: async (...[params, ctx]) => dispatchCompactMutation("accept_proposal", params, ctx, (reqCtx) => lifecycle.acceptProposal(params, reqCtx))
+    },
+    ...lifecycle?.controlMediaBuy && {
+      controlMediaBuy: async (...[params, ctx]) => dispatchCompactMutation("control_media_buy", params, ctx, (reqCtx) => lifecycle.controlMediaBuy(params, reqCtx))
+    },
     ...(sales?.getProducts || proposalManager) && {
       getProducts: async (...[params, ctx]) => {
         const responseWireMode = creativeWireModeForRequest(
@@ -3115,7 +3299,7 @@ function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observab
         );
       }
     },
-    ...sales?.getMediaBuyDelivery && {
+    ...getMediaBuyDelivery && {
       getMediaBuyDelivery: async (...[params, ctx]) => {
         const responseWireMode = creativeWireModeForRequest(ctx, creativeWireMode, params);
         const reqCtx = ctxFor(ctx, params);
@@ -3135,7 +3319,7 @@ function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observab
         }
         return projectSync(
           async () => {
-            const result = await sales.getMediaBuyDelivery(asValidatedDomainRequest(params), reqCtx);
+            const result = await getMediaBuyDelivery(asValidatedDomainRequest(params), reqCtx);
             warnIfTruncatedMultiIdResponse(
               "getMediaBuyDelivery",
               "media_buy_ids",
@@ -3168,13 +3352,13 @@ function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observab
     // platform-derived handler when absent lets `mergeHandlers` pick up the
     // adopter's custom handler from `opts.legacyHandlers.mediaBuy` instead of throwing
     // `sales.getMediaBuys is not a function`.
-    ...sales?.getMediaBuys && {
+    ...getMediaBuys && {
       getMediaBuys: async (...[params, ctx]) => {
         const responseWireMode = creativeWireModeForRequest(ctx, creativeWireMode, params);
         const reqCtx = ctxFor(ctx, params);
         return projectSync(
           async () => {
-            const result = await sales.getMediaBuys(asValidatedDomainRequest(params), reqCtx);
+            const result = await getMediaBuys(asValidatedDomainRequest(params), reqCtx);
             warnIfTruncatedMultiIdResponse(
               "getMediaBuys",
               "media_buy_ids",