@adcp/sdk 14.0.0-rc.49 → 14.0.0-rc.51

package/dist/lib/core/SingleAgentClient.js

@@ -68,6 +68,8 @@ var import_a2a_discovery = require('../utils/a2a-discovery.js');
 var crypto = __toESM(require("crypto"));
 var import_abort2 = require('../protocols/abort.js');
 var import_capabilities = require('../utils/capabilities.js');
+var import_errors3 = require('../errors/index.js');
+var import_account_resolution = require('./account-resolution.js');
 var import_request_normalizer = require('../utils/request-normalizer.js');
 var import_global_async_local_storage = require('../utils/global-async-local-storage.js');
 var import_validate_user_agent = require('../utils/validate-user-agent.js');
@@ -249,12 +251,18 @@ function canonicalAccountRoutingSnapshot(value) {
   if (typeof sourceBrand.domain !== "string") return void 0;
   const brand = Object.freeze({
     domain: sourceBrand.domain,
-    ...typeof sourceBrand.brand_id === "string" ? { brand_id: sourceBrand.brand_id } : {}
+    ...typeof sourceBrand.brand_id === "string" ? { brand_id: sourceBrand.brand_id } : {},
+    ...Array.isArray(sourceBrand.countries) && sourceBrand.countries.every((country) => typeof country === "string") ? { countries: Object.freeze([...sourceBrand.countries].sort()) } : {}
   });
+  const operatorUnit = account.operator_unit;
+  const unitId = operatorUnit && typeof operatorUnit === "object" && !Array.isArray(operatorUnit) ? operatorUnit.id : void 0;
   return Object.freeze({
     brand,
     operator: account.operator,
-    ...typeof account.sandbox === "boolean" ? { sandbox: account.sandbox } : {}
+    ...typeof unitId === "string" ? { operator_unit: Object.freeze({ id: unitId }) } : {},
+    ...typeof account.currency === "string" ? { currency: account.currency } : {},
+    ...typeof account.timezone === "string" ? { timezone: account.timezone } : {},
+    sandbox: account.sandbox === true
   });
 }
 function canonicalOptionRefRoutingSnapshot(value) {
@@ -514,6 +522,13 @@ function snapshotTaskOptions(options) {
     }
   };
 }
+function assertRawMethodForGovernedPayload(taskType, options) {
+  if (options?.preserveGovernedPayload) {
+    throw new import_errors.ConfigurationError(
+      `Governed ${taskType} requires the raw legacy task method; canonical creative projection can reshape approved arguments.`
+    );
+  }
+}
 const PRIMARY_ADCP_TASK_NAMES = {
   get_products: true,
   list_products: true,
@@ -2895,17 +2910,17 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
   async executeAndHandleWithinDeadline(taskType, handlerName, params, inputHandler, options, transformCompletedResponse, legacyFormatConverter, canonicalRequest, projectionCatalogs) {
     (0, import_abort2.throwIfAborted)(options?.signal);
     const canonicalCreativeInvocation = CANONICAL_CREATIVE_ACTIVITY_TASKS.has(taskType) || canonicalRequest !== void 0;
-    let normalizedParams = (0, import_request_normalizer.normalizeRequestParams)(taskType, params, {
+    let normalizedParams = options?.preserveGovernedPayload ? params : (0, import_request_normalizer.normalizeRequestParams)(taskType, params, {
       skipIdempotencyAutoInject: options?.skipIdempotencyAutoInject,
       skipAccountValidation: options?.skipAccountValidation
     });
     if (!options?.skipRequestValidation) assertNoPrincipalIdentityInput(taskType, normalizedParams);
     this.assertRequestSupportedByConfiguredVersion(taskType, normalizedParams, options, canonicalCreativeInvocation);
     this.assertDurablePropertyListCredentialSupported(taskType, normalizedParams);
-    if (!options?.skipIdempotencyAutoInject && (0, import_idempotency.requestUsesIdempotency)(taskType, normalizedParams) && normalizedParams && typeof normalizedParams === "object" && !normalizedParams.idempotency_key) {
+    if (!options?.skipIdempotencyAutoInject && !options?.preserveGovernedPayload && (0, import_idempotency.requestUsesIdempotency)(taskType, normalizedParams) && normalizedParams && typeof normalizedParams === "object" && !normalizedParams.idempotency_key) {
       normalizedParams = { ...normalizedParams, idempotency_key: (0, import_idempotency.generateIdempotencyKey)() };
     }
-    if (!options?.skipIdempotencyAutoInject && !options?.skipAccountValidation && !options?.skipRequestValidation && !(0, import_schema_loader.isExternalSchemaRootActive)(this.resolvedAdcpVersion)) {
+    if (!options?.skipIdempotencyAutoInject && !options?.skipAccountValidation && !options?.skipRequestValidation && !options?.preserveGovernedPayload && !(0, import_schema_loader.isExternalSchemaRootActive)(this.resolvedAdcpVersion)) {
       this.validateRequest(taskType, normalizedParams);
     }
     await this.validateTaskFeatures(taskType, options);
@@ -2921,7 +2936,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     }
     const agent = await this.ensureEndpointDiscovered(options);
     (0, import_abort2.throwIfAborted)(options?.signal);
-    if (!options?.skipIdempotencyAutoInject && !options?.skipAccountValidation && !options?.skipRequestValidation) {
+    if (!options?.skipIdempotencyAutoInject && !options?.skipAccountValidation && !options?.skipRequestValidation && !options?.preserveGovernedPayload) {
       this.executor.validateRequest(taskType, normalizedParams);
     }
     const capabilityDiscoveryContext = {};
@@ -2944,7 +2959,12 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       capabilityDiscoveryContext.capabilities
     );
     const inputSchemaStripLogs = [];
-    const { params: adaptedParams, driftLogs: adaptDriftLogs } = this.adaptRequest(
+    if (options?.preserveGovernedPayload && serverVersion !== "v3") {
+      throw new import_errors.ConfigurationError(
+        "Governed storyboard requests require a v3 seller to preserve the approved payload."
+      );
+    }
+    const { params: adaptedParams, driftLogs: adaptDriftLogs } = options?.preserveGovernedPayload ? { params: normalizedParams, driftLogs: [] } : this.adaptRequest(
       taskType,
       normalizedParams,
       serverVersion,
@@ -4054,28 +4074,67 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       legacyFormatConverter,
       projectionCatalogs ?? this.config.projectionCatalogs
     );
-    const account = canonicalAccountRoutingSnapshot(params.account);
-    return this.executeAndHandle(
-      "get_products",
-      "onGetProductsStatusChange",
-      params,
-      inputHandler,
-      taskOptions,
-      (data) => {
-        const { response, diagnostics } = (0, import_augment_response.toCanonicalOnlyResponse)(data, {
-          legacyFormatConverter: effectiveLegacyFormatConverter,
-          projectionCatalogs: projectionCatalogs ?? this.config.projectionCatalogs
-        });
-        const authoritativeProducts = Array.isArray(data.products) ? data.products : response.products;
-        this.rememberCanonicalProductRoutes(response.products, account, authoritativeProducts);
-        const { _message: _dropLegacyMessage, ...canonical } = response;
-        void _dropLegacyMessage;
-        return { ...canonical, projection: { diagnostics } };
-      },
-      effectiveLegacyFormatConverter,
-      void 0,
-      projectionCatalogs
-    );
+    return (0, import_task_deadline.withTaskDeadline)(snapshotTaskOptions(taskOptions), async (effectiveOptions) => {
+      this.assertRequestSupportedByConfiguredVersion("get_products", params, effectiveOptions);
+      let request = params;
+      const legacyAccountId = request.account_id;
+      const accountReference = request.account ?? (typeof legacyAccountId === "string" && legacyAccountId ? { account_id: legacyAccountId } : void 0);
+      if (!request.account && typeof legacyAccountId === "string" && legacyAccountId) {
+        const { account_id: _legacyAccountId, ...rest } = request;
+        void _legacyAccountId;
+        request = { ...rest, account: { account_id: legacyAccountId } };
+      }
+      if (!effectiveOptions.skipRequestValidation && this.config.validateFeatures !== false) {
+        const capabilities = await this.getCapabilities(effectiveOptions);
+        const sellerDeclares31 = capabilities.servedVersion !== void 0 ? !(0, import_adcp_version_config.isPre31AdcpVersion)(capabilities.servedVersion) : capabilities.supportedVersions?.some((version) => !(0, import_adcp_version_config.isPre31AdcpVersion)(version)) === true;
+        const sellerDeclaresBuyingModes = Array.isArray(
+          capabilities._raw?.media_buy?.buying_modes
+        );
+        if (!capabilities._synthetic) {
+          const effectiveMode = request.buying_mode ?? (request.brief ? "brief" : void 0);
+          if (effectiveMode && (sellerDeclares31 || sellerDeclaresBuyingModes) && !(0, import_capabilities.supportsBuyingMode)(capabilities, effectiveMode)) {
+            throw new import_errors3.UnsupportedBuyingModeError(effectiveMode, capabilities.buyingModes ?? ["brief"]);
+          }
+          if (!effectiveOptions.skipAccountValidation && !accountReference && capabilities.account?.requiredForProducts) {
+            throw new import_errors3.AccountRequiredError(
+              capabilities.account.requireOperatorAuth ? "explicit" : "implicit",
+              "get_products"
+            );
+          }
+        }
+        if (!request.buying_mode && !request.brief) {
+          const legacySeller = capabilities._synthetic || !sellerDeclares31 && !sellerDeclaresBuyingModes;
+          if (!legacySeller && !(0, import_capabilities.supportsBuyingMode)(capabilities, "wholesale")) {
+            throw new import_errors3.UnsupportedBuyingModeError(void 0, capabilities.buyingModes ?? ["brief"]);
+          }
+        }
+      }
+      if (!request.buying_mode && !request.brief) {
+        request = { ...request, buying_mode: "wholesale" };
+      }
+      const account = canonicalAccountRoutingSnapshot(accountReference);
+      return this.executeAndHandle(
+        "get_products",
+        "onGetProductsStatusChange",
+        request,
+        inputHandler,
+        effectiveOptions,
+        (data) => {
+          const { response, diagnostics } = (0, import_augment_response.toCanonicalOnlyResponse)(data, {
+            legacyFormatConverter: effectiveLegacyFormatConverter,
+            projectionCatalogs: projectionCatalogs ?? this.config.projectionCatalogs
+          });
+          const authoritativeProducts = Array.isArray(data.products) ? data.products : response.products;
+          this.rememberCanonicalProductRoutes(response.products, account, authoritativeProducts);
+          const { _message: _dropLegacyMessage, ...canonical } = response;
+          void _dropLegacyMessage;
+          return { ...canonical, projection: { diagnostics } };
+        },
+        effectiveLegacyFormatConverter,
+        void 0,
+        projectionCatalogs
+      );
+    });
   }
   /** Discover products through the compact AdCP 3.2 catalog task. */
   async listProducts(params, inputHandler, options) {
@@ -4089,11 +4148,14 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
   }
   /** @deprecated Explicit raw-wire escape hatch for migration tooling. */
   async getProductsLegacy(params, inputHandler, options) {
-    return this.executeTaskUnprojected("get_products", params, inputHandler, options);
+    const request = params.buying_mode || params.brief ? params : { ...params, buying_mode: "wholesale" };
+    return this.executeTaskUnprojected("get_products", request, inputHandler, options);
   }
   /** @internal Run final legacy get_products adaptation before an application-owned atomic mutation claim. */
   async getProductsLegacyWithPreDispatch(params, beforeDispatch, inputHandler, options) {
-    const requestSnapshot = structuredClone(params);
+    const requestSnapshot = structuredClone(
+      params.buying_mode || params.brief ? params : { ...params, buying_mode: "wholesale" }
+    );
     return this.executeTaskUnprojected(
       "get_products",
       requestSnapshot,
@@ -4132,6 +4194,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
    * @param options - Task execution options
    */
   async createMediaBuy(params, inputHandler, options) {
+    assertRawMethodForGovernedPayload("create_media_buy", options);
     this.assertDurableProjectionOverrideSupported(options?.legacyFormatConverter);
     const requestSnapshot = (0, import_legacy_metadata.structuredCloneWithLegacyCreativeMetadata)(params);
     const projectionCatalogs = options?.projectionCatalogs ? structuredClone(options.projectionCatalogs) : void 0;
@@ -4261,6 +4324,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
    * @param options - Task execution options
    */
   async updateMediaBuy(params, inputHandler, options) {
+    assertRawMethodForGovernedPayload("update_media_buy", options);
     this.assertDurableProjectionOverrideSupported(options?.legacyFormatConverter);
     const requestSnapshot = (0, import_legacy_metadata.structuredCloneWithLegacyCreativeMetadata)(params);
     const projectionCatalogs = options?.projectionCatalogs ? structuredClone(options.projectionCatalogs) : void 0;
@@ -4329,6 +4393,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
    * @param options - Task execution options
    */
   async syncCreatives(params, inputHandler, options) {
+    assertRawMethodForGovernedPayload("sync_creatives", options);
     this.assertDurableProjectionOverrideSupported(
       options?.creativeFormatProjection?.legacyFormatConverter ?? options?.legacyFormatConverter
     );
@@ -4787,6 +4852,140 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
       options
     );
   }
+  /**
+   * Resolve an account for the authenticated caller. Explicit-account sellers
+   * are discovered with list_accounts; implicit-account sellers are registered
+   * with sync_accounts and addressed by their natural key.
+   */
+  async resolveAccount(hints = {}, options, onTaskResult) {
+    return (0, import_task_deadline.withTaskDeadline)(snapshotTaskOptions(options), async (effectiveOptions) => {
+      const capabilities = await this.getCapabilities(effectiveOptions);
+      if (capabilities._synthetic || !capabilities.account) {
+        throw new import_errors3.AccountRequiredError(
+          "explicit",
+          "resolveAccount",
+          "The seller did not provide an account contract. Probe get_adcp_capabilities or pass an account reference explicitly."
+        );
+      }
+      if (capabilities.account.requireOperatorAuth) {
+        const accounts = [];
+        const seenCursors = /* @__PURE__ */ new Set();
+        let cursor;
+        for (let page = 0; page < 100; page++) {
+          const result2 = await this.listAccounts(
+            {
+              status: "active",
+              sandbox: hints.sandbox ?? false,
+              ...cursor !== void 0 && { pagination: { cursor } }
+            },
+            void 0,
+            effectiveOptions
+          );
+          onTaskResult?.(result2);
+          if (!result2.success || result2.status !== "completed" || !result2.data || !("accounts" in result2.data) || !Array.isArray(result2.data.accounts)) {
+            throw new Error("list_accounts did not return a completed account list.");
+          }
+          accounts.push(...result2.data.accounts);
+          if (!result2.data.pagination?.has_more) return (0, import_account_resolution.selectListedAccount)(accounts, hints);
+          const nextCursor = result2.data.pagination.cursor;
+          if (!nextCursor || seenCursors.has(nextCursor)) break;
+          seenCursors.add(nextCursor);
+          cursor = nextCursor;
+        }
+        throw new import_errors3.AccountRequiredError(
+          "explicit",
+          "resolveAccount",
+          "Could not complete list_accounts pagination. Select an account_id explicitly after listing accounts."
+        );
+      }
+      if (!hints.brand?.domain || !hints.operator) {
+        throw new import_errors3.AccountRequiredError(
+          "implicit",
+          "resolveAccount",
+          "Implicit-account sellers require both brand and operator to sync an account."
+        );
+      }
+      const uses32NaturalKey = hints.operatorUnit !== void 0 || hints.currency !== void 0 || hints.timezone !== void 0;
+      const sellerServes32 = capabilities.servedVersion ? !(0, import_adcp_version_config.isPre32AdcpVersion)(capabilities.servedVersion) : capabilities.supportedVersions?.some((version) => !(0, import_adcp_version_config.isPre32AdcpVersion)(version)) === true;
+      if (uses32NaturalKey && ((0, import_adcp_version_config.isPre32AdcpVersion)(this.resolvedAdcpVersion) || !sellerServes32)) {
+        throw new import_errors3.AccountRequiredError(
+          "implicit",
+          "resolveAccount",
+          "Operator unit, account currency, and account timezone require AdCP 3.2 on both buyer and seller."
+        );
+      }
+      const timezone = capabilities.account.timezone;
+      if (timezone?.accountSelection === "buyer_selected") {
+        if (!hints.timezone || !timezone.supportedTimezones?.includes(hints.timezone)) {
+          throw new import_errors3.AccountRequiredError(
+            "implicit",
+            "resolveAccount",
+            "Choose a supported account timezone before sync_accounts."
+          );
+        }
+      } else if (hints.timezone && timezone) {
+        throw new import_errors3.AccountRequiredError(
+          "implicit",
+          "resolveAccount",
+          "This seller does not accept a buyer-selected account timezone."
+        );
+      }
+      const currencyModes = capabilities.account.supportedAccountCurrencyModes;
+      if (currencyModes?.length === 1 && currencyModes[0] === "fixed" && !hints.currency) {
+        throw new import_errors3.AccountRequiredError("implicit", "resolveAccount", "This seller requires a fixed account currency.");
+      }
+      if (hints.currency && currencyModes?.length === 1 && currencyModes[0] === "per_media_buy") {
+        throw new import_errors3.AccountRequiredError("implicit", "resolveAccount", "This seller selects currency per media buy.");
+      }
+      const account = {
+        brand: hints.brand,
+        operator: hints.operator,
+        ...hints.operatorUnit !== void 0 && { operator_unit: hints.operatorUnit },
+        ...hints.currency !== void 0 && { currency: hints.currency },
+        ...hints.timezone !== void 0 && { timezone: hints.timezone },
+        ...hints.sandbox !== void 0 && { sandbox: hints.sandbox }
+      };
+      const supportedBilling = capabilities.account.supportedBilling;
+      const billing = hints.billing ?? capabilities.account.defaultBilling ?? (supportedBilling.length === 1 ? supportedBilling[0] : void 0);
+      if (!billing || supportedBilling.length > 0 && !supportedBilling.includes(billing)) {
+        throw new import_errors3.AccountRequiredError(
+          "implicit",
+          "resolveAccount",
+          `Choose a supported billing party for sync_accounts (seller supports: ${supportedBilling.join(", ") || "(none)"}).`
+        );
+      }
+      const result = await this.syncAccounts(
+        {
+          accounts: [
+            {
+              ...account,
+              billing
+            }
+          ]
+        },
+        void 0,
+        effectiveOptions
+      );
+      onTaskResult?.(result);
+      if (!result.success || result.status !== "completed" || !result.data || !("accounts" in result.data) || !Array.isArray(result.data.accounts)) {
+        throw new Error("sync_accounts did not return a completed account result.");
+      }
+      const synced = result.data.accounts.find(
+        (row) => row.brand?.domain === hints.brand.domain && row.operator === hints.operator && (!hints.brand.brand_id || row.brand.brand_id === hints.brand.brand_id) && (0, import_account_resolution.sameCountrySet)(hints.brand.countries, row.brand.countries) && (!hints.operatorUnit || row.operator_unit?.id === hints.operatorUnit.id) && (!hints.currency || row.currency === hints.currency) && (!hints.timezone || row.timezone === hints.timezone) && (row.sandbox === void 0 || row.sandbox === true === (hints.sandbox === true))
+      );
+      if (synced?.status === "pending_approval") {
+        throw new import_errors3.AccountPendingApprovalError(account, synced.account_id);
+      }
+      if (!synced || synced.action === "failed" || synced.status !== "active") {
+        throw new import_errors3.AccountRequiredError(
+          "implicit",
+          "resolveAccount",
+          "sync_accounts did not establish an active account for the requested brand and operator."
+        );
+      }
+      return account;
+    });
+  }
   /**
    * Sync accounts
    */
@@ -5055,7 +5254,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     let detectedServerVersion;
     let detectedServerVersionSynthetic;
     try {
-      const normalizedParams = (0, import_request_normalizer.normalizeRequestParams)(taskName, params, {
+      const normalizedParams = options?.preserveGovernedPayload ? params : (0, import_request_normalizer.normalizeRequestParams)(taskName, params, {
         skipIdempotencyAutoInject: options?.skipIdempotencyAutoInject,
         skipAccountValidation: options?.skipAccountValidation
       });
@@ -5067,7 +5266,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         await this.requireSupportedMajor(taskName, options);
       }
       const agent = await this.ensureEndpointDiscovered(options);
-      if (!options?.skipIdempotencyAutoInject && !options?.skipAccountValidation && !options?.skipRequestValidation) {
+      if (!options?.skipIdempotencyAutoInject && !options?.skipAccountValidation && !options?.skipRequestValidation && !options?.preserveGovernedPayload) {
         this.executor.validateRequest(taskName, normalizedParams);
       }
       const capabilityDiscoveryContext = {};
@@ -5091,7 +5290,12 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
         capabilityDiscoveryContext.capabilities
       );
       const inputSchemaStripLogs = [];
-      const { params: adaptedParams, driftLogs: adaptDriftLogs } = this.adaptRequest(
+      if (options?.preserveGovernedPayload && serverVersion !== "v3") {
+        throw new import_errors.ConfigurationError(
+          "Governed storyboard requests require a v3 seller to preserve the approved payload."
+        );
+      }
+      const { params: adaptedParams, driftLogs: adaptDriftLogs } = options?.preserveGovernedPayload ? { params: normalizedParams, driftLogs: [] } : this.adaptRequest(
         taskName,
         normalizedParams,
         serverVersion,