@adcp/sdk 14.0.0-rc.50 → 14.0.0-rc.52

package/dist/lib/core/SingleAgentClient.mjs

@@ -119,8 +119,11 @@ import {
   resolveFeature,
   listDeclaredFeatures,
   TASK_FEATURE_MAP,
-  assertValidIdempotencyReplayTtlSeconds
+  assertValidIdempotencyReplayTtlSeconds,
+  supportsBuyingMode
 } from "../utils/capabilities.mjs";
+import { AccountPendingApprovalError, AccountRequiredError, UnsupportedBuyingModeError } from "../errors/index.mjs";
+import { sameCountrySet, selectListedAccount } from "./account-resolution.mjs";
 import { normalizeRequestParams } from "../utils/request-normalizer.mjs";
 import { globalAsyncLocalStorage } from "../utils/global-async-local-storage.mjs";
 import { validateUserAgent } from "../utils/validate-user-agent.mjs";
@@ -310,12 +313,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) {
@@ -575,6 +584,13 @@ function snapshotTaskOptions(options) {
     }
   };
 }
+function assertRawMethodForGovernedPayload(taskType, options) {
+  if (options?.preserveGovernedPayload) {
+    throw new 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,
@@ -2956,17 +2972,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) {
     throwIfAborted(options?.signal);
     const canonicalCreativeInvocation = CANONICAL_CREATIVE_ACTIVITY_TASKS.has(taskType) || canonicalRequest !== void 0;
-    let normalizedParams = normalizeRequestParams(taskType, params, {
+    let normalizedParams = options?.preserveGovernedPayload ? params : 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 && requestUsesIdempotency(taskType, normalizedParams) && normalizedParams && typeof normalizedParams === "object" && !normalizedParams.idempotency_key) {
+    if (!options?.skipIdempotencyAutoInject && !options?.preserveGovernedPayload && requestUsesIdempotency(taskType, normalizedParams) && normalizedParams && typeof normalizedParams === "object" && !normalizedParams.idempotency_key) {
       normalizedParams = { ...normalizedParams, idempotency_key: generateIdempotencyKey() };
     }
-    if (!options?.skipIdempotencyAutoInject && !options?.skipAccountValidation && !options?.skipRequestValidation && !isExternalSchemaRootActive(this.resolvedAdcpVersion)) {
+    if (!options?.skipIdempotencyAutoInject && !options?.skipAccountValidation && !options?.skipRequestValidation && !options?.preserveGovernedPayload && !isExternalSchemaRootActive(this.resolvedAdcpVersion)) {
       this.validateRequest(taskType, normalizedParams);
     }
     await this.validateTaskFeatures(taskType, options);
@@ -2982,7 +2998,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     }
     const agent = await this.ensureEndpointDiscovered(options);
     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 = {};
@@ -3005,7 +3021,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 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,
@@ -4115,28 +4136,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 } = 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 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 ? !isPre31AdcpVersion(capabilities.servedVersion) : capabilities.supportedVersions?.some((version) => !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) && !supportsBuyingMode(capabilities, effectiveMode)) {
+            throw new UnsupportedBuyingModeError(effectiveMode, capabilities.buyingModes ?? ["brief"]);
+          }
+          if (!effectiveOptions.skipAccountValidation && !accountReference && capabilities.account?.requiredForProducts) {
+            throw new AccountRequiredError(
+              capabilities.account.requireOperatorAuth ? "explicit" : "implicit",
+              "get_products"
+            );
+          }
+        }
+        if (!request.buying_mode && !request.brief) {
+          const legacySeller = capabilities._synthetic || !sellerDeclares31 && !sellerDeclaresBuyingModes;
+          if (!legacySeller && !supportsBuyingMode(capabilities, "wholesale")) {
+            throw new 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 } = 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) {
@@ -4150,11 +4210,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,
@@ -4193,6 +4256,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 = structuredCloneWithLegacyCreativeMetadata(params);
     const projectionCatalogs = options?.projectionCatalogs ? structuredClone(options.projectionCatalogs) : void 0;
@@ -4322,6 +4386,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 = structuredCloneWithLegacyCreativeMetadata(params);
     const projectionCatalogs = options?.projectionCatalogs ? structuredClone(options.projectionCatalogs) : void 0;
@@ -4390,6 +4455,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
     );
@@ -4848,6 +4914,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 withTaskDeadline(snapshotTaskOptions(options), async (effectiveOptions) => {
+      const capabilities = await this.getCapabilities(effectiveOptions);
+      if (capabilities._synthetic || !capabilities.account) {
+        throw new 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 selectListedAccount(accounts, hints);
+          const nextCursor = result2.data.pagination.cursor;
+          if (!nextCursor || seenCursors.has(nextCursor)) break;
+          seenCursors.add(nextCursor);
+          cursor = nextCursor;
+        }
+        throw new 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 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 ? !isPre32AdcpVersion(capabilities.servedVersion) : capabilities.supportedVersions?.some((version) => !isPre32AdcpVersion(version)) === true;
+      if (uses32NaturalKey && (isPre32AdcpVersion(this.resolvedAdcpVersion) || !sellerServes32)) {
+        throw new 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 AccountRequiredError(
+            "implicit",
+            "resolveAccount",
+            "Choose a supported account timezone before sync_accounts."
+          );
+        }
+      } else if (hints.timezone && timezone) {
+        throw new 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 AccountRequiredError("implicit", "resolveAccount", "This seller requires a fixed account currency.");
+      }
+      if (hints.currency && currencyModes?.length === 1 && currencyModes[0] === "per_media_buy") {
+        throw new 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 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) && 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 AccountPendingApprovalError(account, synced.account_id);
+      }
+      if (!synced || synced.action === "failed" || synced.status !== "active") {
+        throw new AccountRequiredError(
+          "implicit",
+          "resolveAccount",
+          "sync_accounts did not establish an active account for the requested brand and operator."
+        );
+      }
+      return account;
+    });
+  }
   /**
    * Sync accounts
    */
@@ -5116,7 +5316,7 @@ Hint: this usually means agent_uri does not include the MCP endpoint path. The S
     let detectedServerVersion;
     let detectedServerVersionSynthetic;
     try {
-      const normalizedParams = normalizeRequestParams(taskName, params, {
+      const normalizedParams = options?.preserveGovernedPayload ? params : normalizeRequestParams(taskName, params, {
         skipIdempotencyAutoInject: options?.skipIdempotencyAutoInject,
         skipAccountValidation: options?.skipAccountValidation
       });
@@ -5128,7 +5328,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 = {};
@@ -5152,7 +5352,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 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,

package/dist/lib/core/TaskExecutor.js

@@ -789,7 +789,7 @@ class TaskExecutor {
     const workingTimeout = this.config.workingTimeout || 12e4;
     const wireAdcpVersion = options.wireAdcpVersion ?? this.config.wireAdcpVersion;
     const versionEnvelope = options.versionEnvelope ?? this.config.versionEnvelope;
-    const idempotencyKey = options.skipIdempotencyAutoInject ? void 0 : resolveIdempotencyKey(taskName, params, serverVersion);
+    const idempotencyKey = options.skipIdempotencyAutoInject || options.preserveGovernedPayload ? void 0 : resolveIdempotencyKey(taskName, params, serverVersion);
     if (idempotencyKey) (0, import_task_deadline.attachTaskDeadlineIdempotencyKey)(options, idempotencyKey);
     if (serverVersion !== "v2" && idempotencyKey && params && typeof params === "object" && !params.idempotency_key) {
       params = { ...params, idempotency_key: idempotencyKey };

package/dist/lib/core/TaskExecutor.mjs

@@ -762,7 +762,7 @@ class TaskExecutor {
     const workingTimeout = this.config.workingTimeout || 12e4;
     const wireAdcpVersion = options.wireAdcpVersion ?? this.config.wireAdcpVersion;
     const versionEnvelope = options.versionEnvelope ?? this.config.versionEnvelope;
-    const idempotencyKey = options.skipIdempotencyAutoInject ? void 0 : resolveIdempotencyKey(taskName, params, serverVersion);
+    const idempotencyKey = options.skipIdempotencyAutoInject || options.preserveGovernedPayload ? void 0 : resolveIdempotencyKey(taskName, params, serverVersion);
     if (idempotencyKey) attachTaskDeadlineIdempotencyKey(options, idempotencyKey);
     if (serverVersion !== "v2" && idempotencyKey && params && typeof params === "object" && !params.idempotency_key) {
       params = { ...params, idempotency_key: idempotencyKey };

package/dist/lib/core/account-resolution.d.mts

@@ -0,0 +1,24 @@
+import type { AccountReference, ListAccountsResponse } from '../types/index.mjs';
+export type ListedAccount = ListAccountsResponse['accounts'][number];
+type NaturalAccountReference = Extract<AccountReference, {
+    brand: unknown;
+}>;
+export declare function sameCountrySet(expected?: readonly string[], actual?: readonly string[]): boolean;
+/** Hints for resolving a seller account against the caller's own credentials. */
+export interface ResolveAccountOptions {
+    brand?: NaturalAccountReference['brand'];
+    operator?: string;
+    operatorUnit?: NaturalAccountReference['operator_unit'];
+    currency?: NaturalAccountReference['currency'];
+    timezone?: NaturalAccountReference['timezone'];
+    sandbox?: boolean;
+    /** Require introspected access to this task when the seller publishes authorization. */
+    forTask?: string;
+    /** Billing party for buyer-declared accounts when the seller has no default. */
+    billing?: 'operator' | 'agent' | 'advertiser';
+    /** An account_id or a callback choosing one of the eligible list_accounts rows. */
+    select?: string | ((accounts: readonly ListedAccount[]) => string);
+}
+/** Select only from active rows returned for the authenticated caller. */
+export declare function selectListedAccount(accounts: readonly ListedAccount[], hints: ResolveAccountOptions): AccountReference;
+export {};

package/dist/lib/core/account-resolution.d.ts

@@ -0,0 +1,24 @@
+import type { AccountReference, ListAccountsResponse } from '../types';
+export type ListedAccount = ListAccountsResponse['accounts'][number];
+type NaturalAccountReference = Extract<AccountReference, {
+    brand: unknown;
+}>;
+export declare function sameCountrySet(expected?: readonly string[], actual?: readonly string[]): boolean;
+/** Hints for resolving a seller account against the caller's own credentials. */
+export interface ResolveAccountOptions {
+    brand?: NaturalAccountReference['brand'];
+    operator?: string;
+    operatorUnit?: NaturalAccountReference['operator_unit'];
+    currency?: NaturalAccountReference['currency'];
+    timezone?: NaturalAccountReference['timezone'];
+    sandbox?: boolean;
+    /** Require introspected access to this task when the seller publishes authorization. */
+    forTask?: string;
+    /** Billing party for buyer-declared accounts when the seller has no default. */
+    billing?: 'operator' | 'agent' | 'advertiser';
+    /** An account_id or a callback choosing one of the eligible list_accounts rows. */
+    select?: string | ((accounts: readonly ListedAccount[]) => string);
+}
+/** Select only from active rows returned for the authenticated caller. */
+export declare function selectListedAccount(accounts: readonly ListedAccount[], hints: ResolveAccountOptions): AccountReference;
+export {};

package/dist/lib/core/account-resolution.js

@@ -0,0 +1,79 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var account_resolution_exports = {};
+__export(account_resolution_exports, {
+  sameCountrySet: () => sameCountrySet,
+  selectListedAccount: () => selectListedAccount
+});
+module.exports = __toCommonJS(account_resolution_exports);
+var import_errors = require('../errors/index.js');
+function sameCountrySet(expected, actual) {
+  if (expected === void 0) return true;
+  if (!actual || expected.length !== actual.length) return false;
+  const sortedExpected = [...expected].sort();
+  const sortedActual = [...actual].sort();
+  return sortedExpected.every((country, index) => country === sortedActual[index]);
+}
+function selectListedAccount(accounts, hints) {
+  const candidates = accounts.filter((account) => {
+    if (typeof account.account_id !== "string" || !account.account_id) return false;
+    if (account.status !== "active") return false;
+    if (hints.forTask && account.authorization && !account.authorization.allowed_tasks.includes(hints.forTask)) {
+      return false;
+    }
+    if (hints.brand) {
+      if (account.brand?.domain !== hints.brand.domain) return false;
+      if (hints.brand.brand_id && account.brand.brand_id !== hints.brand.brand_id) return false;
+      if (!sameCountrySet(hints.brand.countries, account.brand.countries)) return false;
+    }
+    if (hints.operator && account.operator !== hints.operator) return false;
+    if (hints.operatorUnit && account.operator_unit?.id !== hints.operatorUnit.id) return false;
+    if (hints.currency && account.currency !== hints.currency) return false;
+    if (hints.timezone && account.timezone !== hints.timezone) return false;
+    if (account.sandbox === true !== (hints.sandbox === true)) return false;
+    return true;
+  });
+  if (candidates.length === 0) {
+    throw new import_errors.AccountRequiredError(
+      "explicit",
+      "resolveAccount",
+      "list_accounts returned no active account matching the supplied brand, operator, and sandbox hints."
+    );
+  }
+  const selectedId = typeof hints.select === "function" ? hints.select(candidates) : hints.select;
+  if (selectedId !== void 0) {
+    if (!candidates.some((account) => account.account_id === selectedId)) {
+      throw new import_errors.AccountRequiredError(
+        "explicit",
+        "resolveAccount",
+        "The selected account_id is not among the active accounts returned for this caller."
+      );
+    }
+    return { account_id: selectedId };
+  }
+  if (candidates.length > 1) {
+    throw new import_errors.AccountAmbiguousError(candidates.map((account) => account.account_id));
+  }
+  return { account_id: candidates[0].account_id };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  sameCountrySet,
+  selectListedAccount
+});

package/dist/lib/core/account-resolution.mjs

@@ -0,0 +1,54 @@
+import { AccountAmbiguousError, AccountRequiredError } from "../errors/index.mjs";
+function sameCountrySet(expected, actual) {
+  if (expected === void 0) return true;
+  if (!actual || expected.length !== actual.length) return false;
+  const sortedExpected = [...expected].sort();
+  const sortedActual = [...actual].sort();
+  return sortedExpected.every((country, index) => country === sortedActual[index]);
+}
+function selectListedAccount(accounts, hints) {
+  const candidates = accounts.filter((account) => {
+    if (typeof account.account_id !== "string" || !account.account_id) return false;
+    if (account.status !== "active") return false;
+    if (hints.forTask && account.authorization && !account.authorization.allowed_tasks.includes(hints.forTask)) {
+      return false;
+    }
+    if (hints.brand) {
+      if (account.brand?.domain !== hints.brand.domain) return false;
+      if (hints.brand.brand_id && account.brand.brand_id !== hints.brand.brand_id) return false;
+      if (!sameCountrySet(hints.brand.countries, account.brand.countries)) return false;
+    }
+    if (hints.operator && account.operator !== hints.operator) return false;
+    if (hints.operatorUnit && account.operator_unit?.id !== hints.operatorUnit.id) return false;
+    if (hints.currency && account.currency !== hints.currency) return false;
+    if (hints.timezone && account.timezone !== hints.timezone) return false;
+    if (account.sandbox === true !== (hints.sandbox === true)) return false;
+    return true;
+  });
+  if (candidates.length === 0) {
+    throw new AccountRequiredError(
+      "explicit",
+      "resolveAccount",
+      "list_accounts returned no active account matching the supplied brand, operator, and sandbox hints."
+    );
+  }
+  const selectedId = typeof hints.select === "function" ? hints.select(candidates) : hints.select;
+  if (selectedId !== void 0) {
+    if (!candidates.some((account) => account.account_id === selectedId)) {
+      throw new AccountRequiredError(
+        "explicit",
+        "resolveAccount",
+        "The selected account_id is not among the active accounts returned for this caller."
+      );
+    }
+    return { account_id: selectedId };
+  }
+  if (candidates.length > 1) {
+    throw new AccountAmbiguousError(candidates.map((account) => account.account_id));
+  }
+  return { account_id: candidates[0].account_id };
+}
+export {
+  sameCountrySet,
+  selectListedAccount
+};

package/dist/lib/errors/index.d.mts

@@ -72,6 +72,33 @@ export declare class UnsupportedTaskError extends ADCPError {
     readonly code = "UNSUPPORTED_TASK";
     constructor(agentId: string, taskName: string, supportedTasks?: string[] | undefined);
 }
+/** Seller did not declare the requested get_products buying mode. */
+export declare class UnsupportedBuyingModeError extends ADCPError {
+    readonly requestedMode: string | undefined;
+    readonly declaredModes: readonly string[];
+    readonly code = "UNSUPPORTED_BUYING_MODE";
+    constructor(requestedMode: string | undefined, declaredModes: readonly string[]);
+}
+/** A seller requires an account reference before an account-scoped request. */
+export declare class AccountRequiredError extends ADCPError {
+    readonly accountModel: 'explicit' | 'implicit';
+    readonly taskName: string;
+    readonly code = "ACCOUNT_REQUIRED";
+    constructor(accountModel: 'explicit' | 'implicit', taskName: string, reason?: string);
+}
+/** Account provisioning succeeded but the seller has not approved its use. */
+export declare class AccountPendingApprovalError extends ADCPError {
+    readonly account: import('../types/index.mjs').AccountReference;
+    readonly accountId?: string | undefined;
+    readonly code = "ACCOUNT_PENDING_APPROVAL";
+    constructor(account: import('../types/index.mjs').AccountReference, accountId?: string | undefined);
+}
+/** More than one active account matches the caller's selection hints. */
+export declare class AccountAmbiguousError extends ADCPError {
+    readonly candidates: readonly string[];
+    readonly code = "ACCOUNT_AMBIGUOUS";
+    constructor(candidates: readonly string[]);
+}
 /**
  * Error thrown when protocol communication fails
  */