@adcp/sdk 14.0.0 → 14.1.0

package/dist/lib/core/product-cache.mjs

@@ -0,0 +1,112 @@
+import { accountReferenceKey } from "./account-key.mjs";
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable);
+  if (value && typeof value === "object")
+    return Object.fromEntries(
+      Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => [k, stable(v)])
+    );
+  return value;
+}
+class ProductCache {
+  constructor(options = {}) {
+    this.options = options;
+    if (options.maxEntries !== void 0 && (!Number.isSafeInteger(options.maxEntries) || options.maxEntries < 1))
+      throw new Error("Product cache maxEntries must be a positive integer.");
+    for (const ttl of [options.publicTtl, options.accountTtl]) {
+      if (ttl !== void 0 && (!Number.isFinite(ttl) || ttl < 0))
+        throw new Error("Product cache TTLs must be nonnegative milliseconds.");
+    }
+  }
+  options;
+  entries = /* @__PURE__ */ new Map();
+  key(sellerScope, params) {
+    const { account, if_wholesale_feed_version: _feed, if_pricing_version: _price, ...query } = params;
+    if (account !== void 0) {
+      if (!account || typeof account !== "object") return void 0;
+      const ref = account;
+      if ("account_id" in ref) {
+        if (typeof ref.account_id !== "string" || !ref.account_id) return void 0;
+      } else if (!ref.brand || typeof ref.brand.domain !== "string" || typeof ref.operator !== "string") {
+        return void 0;
+      }
+    }
+    return JSON.stringify([
+      sellerScope,
+      account ? accountReferenceKey(account) : "public",
+      stable(query)
+    ]);
+  }
+  read(scope, params, allowExpired = false) {
+    const key = this.key(scope, params);
+    if (!key) return void 0;
+    const entry = this.entries.get(key);
+    if (!entry) return void 0;
+    const ttl = entry.scope === "public" ? this.options.publicTtl ?? 6e4 : this.options.accountTtl ?? 3e4;
+    if (!allowExpired && Date.now() - entry.storedAt >= ttl) return void 0;
+    return {
+      ...entry.result,
+      data: structuredClone(entry.result.data),
+      metadata: structuredClone(entry.result.metadata),
+      ...entry.result.debug_logs && { debug_logs: structuredClone(entry.result.debug_logs) }
+    };
+  }
+  conditionalParams(scope, params) {
+    if (params.if_wholesale_feed_version !== void 0 || params.if_pricing_version !== void 0) return params;
+    const result = this.read(scope, params, true);
+    const data = result?.data;
+    if (typeof data?.wholesale_feed_version !== "string") return params;
+    return {
+      ...params,
+      if_wholesale_feed_version: data.wholesale_feed_version,
+      ...typeof data.pricing_version === "string" && { if_pricing_version: data.pricing_version }
+    };
+  }
+  write(scope, params, result, conditionalSnapshot) {
+    const key = this.key(scope, params);
+    if (!key) return result;
+    if (!result.success || result.status !== "completed" || !result.data || typeof result.data !== "object")
+      return result;
+    const data = result.data;
+    if (data.cache_scope !== "public" && data.cache_scope !== "account") {
+      this.entries.delete(key);
+      return result;
+    }
+    if (data.cache_scope === "account" && !params.account) {
+      this.entries.delete(key);
+      return result;
+    }
+    let completed = result;
+    if (data.unchanged === true) {
+      if (typeof data.wholesale_feed_version !== "string") return result;
+      const old = conditionalSnapshot?.data ? { result: conditionalSnapshot, scope: conditionalSnapshot.data.cache_scope } : this.entries.get(key);
+      const oldData = old?.result.data;
+      if (!old || old.scope !== data.cache_scope || !oldData || data.wholesale_feed_version !== oldData.wholesale_feed_version || data.pricing_version !== void 0 && data.pricing_version !== oldData.pricing_version)
+        return result;
+      if (params.if_wholesale_feed_version !== void 0 || params.if_pricing_version !== void 0) return result;
+      completed = { ...result, data: structuredClone(oldData) };
+    } else if (!Array.isArray(data.products)) return result;
+    if (!this.entries.has(key) && this.entries.size >= (this.options.maxEntries ?? 1e3))
+      this.entries.delete(this.entries.keys().next().value);
+    this.entries.set(key, {
+      result: {
+        ...completed,
+        data: structuredClone(completed.data),
+        metadata: structuredClone(completed.metadata),
+        ...completed.debug_logs && { debug_logs: structuredClone(completed.debug_logs) }
+      },
+      storedAt: Date.now(),
+      scope: data.cache_scope
+    });
+    return completed;
+  }
+  clear() {
+    this.entries.clear();
+  }
+}
+function createProductCache(options = {}) {
+  return new ProductCache(options);
+}
+export {
+  ProductCache,
+  createProductCache
+};

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

@@ -1,3 +1,4 @@
+import { RequestSigningErrorCodeMetadata } from '../types/enums.generated.mjs';
 /**
  * Base class for all ADCP client errors
  */
@@ -84,6 +85,7 @@ export declare class AccountRequiredError extends ADCPError {
     readonly accountModel: 'explicit' | 'implicit';
     readonly taskName: string;
     readonly code = "ACCOUNT_REQUIRED";
+    readonly fault: "buyer_setup";
     constructor(accountModel: 'explicit' | 'implicit', taskName: string, reason?: string);
 }
 /** Account provisioning succeeded but the seller has not approved its use. */
@@ -91,6 +93,7 @@ export declare class AccountPendingApprovalError extends ADCPError {
     readonly account: import('../types/index.mjs').AccountReference;
     readonly accountId?: string | undefined;
     readonly code = "ACCOUNT_PENDING_APPROVAL";
+    readonly fault: "buyer_setup";
     constructor(account: import('../types/index.mjs').AccountReference, accountId?: string | undefined);
 }
 /** More than one active account matches the caller's selection hints. */
@@ -99,6 +102,27 @@ export declare class AccountAmbiguousError extends ADCPError {
     readonly code = "ACCOUNT_AMBIGUOUS";
     constructor(candidates: readonly string[]);
 }
+/** Buyer setup errors must be excluded from seller-health failure counts. */
+export declare abstract class BuyerSetupError extends ADCPError {
+    readonly fault: "buyer_setup";
+}
+export declare class AccountNotFoundError extends BuyerSetupError {
+    readonly code: string;
+    constructor(message?: string);
+}
+export declare class AccountSetupRequiredError extends BuyerSetupError {
+    readonly code: string;
+    constructor(message?: string);
+}
+export declare class AccountPaymentRequiredError extends BuyerSetupError {
+    readonly code: string;
+    constructor(message?: string);
+}
+export declare class AccountNotProvisionedError extends AccountNotFoundError {
+    readonly account: import('../types/index.mjs').AccountReference;
+    readonly taskName: string;
+    constructor(account: import('../types/index.mjs').AccountReference, taskName: string);
+}
 /**
  * Error thrown when protocol communication fails
  */
@@ -172,6 +196,12 @@ export interface AuthChallengeInfo {
     error?: string;
     error_description?: string;
 }
+/** Diagnostics from the original HTTP response to an SDK-signed request. */
+export interface SignedRequestRejectionInfo {
+    status: number;
+    /** Untrusted seller text, already bounded and redacted by the transport. */
+    responseBody?: string;
+}
 /**
  * Error thrown when authentication is required to access an MCP endpoint
  *
@@ -215,7 +245,16 @@ export declare class AuthenticationRequiredError extends ADCPError {
     readonly oauthMetadata?: OAuthMetadataInfo | undefined;
     readonly challenge?: AuthChallengeInfo | undefined;
     readonly code = "AUTHENTICATION_REQUIRED";
-    constructor(agentUrl: string, oauthMetadata?: OAuthMetadataInfo | undefined, message?: string, challenge?: AuthChallengeInfo | undefined);
+    readonly signatureErrorCode?: keyof typeof RequestSigningErrorCodeMetadata;
+    readonly requestSigned?: boolean;
+    readonly status?: number;
+    /**
+     * Bounded, redacted seller diagnostic. Non-enumerable: do not forward this
+     * untrusted text to automated prompts or treat it as recovery instructions.
+     * Read it directly as `error.responseBody`; spread and JSON serialization omit it.
+     */
+    readonly responseBody?: string;
+    constructor(agentUrl: string, oauthMetadata?: OAuthMetadataInfo | undefined, message?: string, challenge?: AuthChallengeInfo | undefined, signedRejection?: SignedRequestRejectionInfo);
     /**
      * Check if OAuth authentication is available
      */

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

@@ -1,3 +1,4 @@
+import { RequestSigningErrorCodeMetadata } from '../types/enums.generated';
 /**
  * Base class for all ADCP client errors
  */
@@ -84,6 +85,7 @@ export declare class AccountRequiredError extends ADCPError {
     readonly accountModel: 'explicit' | 'implicit';
     readonly taskName: string;
     readonly code = "ACCOUNT_REQUIRED";
+    readonly fault: "buyer_setup";
     constructor(accountModel: 'explicit' | 'implicit', taskName: string, reason?: string);
 }
 /** Account provisioning succeeded but the seller has not approved its use. */
@@ -91,6 +93,7 @@ export declare class AccountPendingApprovalError extends ADCPError {
     readonly account: import('../types').AccountReference;
     readonly accountId?: string | undefined;
     readonly code = "ACCOUNT_PENDING_APPROVAL";
+    readonly fault: "buyer_setup";
     constructor(account: import('../types').AccountReference, accountId?: string | undefined);
 }
 /** More than one active account matches the caller's selection hints. */
@@ -99,6 +102,27 @@ export declare class AccountAmbiguousError extends ADCPError {
     readonly code = "ACCOUNT_AMBIGUOUS";
     constructor(candidates: readonly string[]);
 }
+/** Buyer setup errors must be excluded from seller-health failure counts. */
+export declare abstract class BuyerSetupError extends ADCPError {
+    readonly fault: "buyer_setup";
+}
+export declare class AccountNotFoundError extends BuyerSetupError {
+    readonly code: string;
+    constructor(message?: string);
+}
+export declare class AccountSetupRequiredError extends BuyerSetupError {
+    readonly code: string;
+    constructor(message?: string);
+}
+export declare class AccountPaymentRequiredError extends BuyerSetupError {
+    readonly code: string;
+    constructor(message?: string);
+}
+export declare class AccountNotProvisionedError extends AccountNotFoundError {
+    readonly account: import('../types').AccountReference;
+    readonly taskName: string;
+    constructor(account: import('../types').AccountReference, taskName: string);
+}
 /**
  * Error thrown when protocol communication fails
  */
@@ -172,6 +196,12 @@ export interface AuthChallengeInfo {
     error?: string;
     error_description?: string;
 }
+/** Diagnostics from the original HTTP response to an SDK-signed request. */
+export interface SignedRequestRejectionInfo {
+    status: number;
+    /** Untrusted seller text, already bounded and redacted by the transport. */
+    responseBody?: string;
+}
 /**
  * Error thrown when authentication is required to access an MCP endpoint
  *
@@ -215,7 +245,16 @@ export declare class AuthenticationRequiredError extends ADCPError {
     readonly oauthMetadata?: OAuthMetadataInfo | undefined;
     readonly challenge?: AuthChallengeInfo | undefined;
     readonly code = "AUTHENTICATION_REQUIRED";
-    constructor(agentUrl: string, oauthMetadata?: OAuthMetadataInfo | undefined, message?: string, challenge?: AuthChallengeInfo | undefined);
+    readonly signatureErrorCode?: keyof typeof RequestSigningErrorCodeMetadata;
+    readonly requestSigned?: boolean;
+    readonly status?: number;
+    /**
+     * Bounded, redacted seller diagnostic. Non-enumerable: do not forward this
+     * untrusted text to automated prompts or treat it as recovery instructions.
+     * Read it directly as `error.responseBody`; spread and JSON serialization omit it.
+     */
+    readonly responseBody?: string;
+    constructor(agentUrl: string, oauthMetadata?: OAuthMetadataInfo | undefined, message?: string, challenge?: AuthChallengeInfo | undefined, signedRejection?: SignedRequestRejectionInfo);
     /**
      * Check if OAuth authentication is available
      */

package/dist/lib/errors/index.js

@@ -20,12 +20,17 @@ var errors_exports = {};
 __export(errors_exports, {
   ADCPError: () => ADCPError,
   AccountAmbiguousError: () => AccountAmbiguousError,
+  AccountNotFoundError: () => AccountNotFoundError,
+  AccountNotProvisionedError: () => AccountNotProvisionedError,
+  AccountPaymentRequiredError: () => AccountPaymentRequiredError,
   AccountPendingApprovalError: () => AccountPendingApprovalError,
   AccountRequiredError: () => AccountRequiredError,
+  AccountSetupRequiredError: () => AccountSetupRequiredError,
   ActionNotAllowedError: () => ActionNotAllowedError,
   AgentNotFoundError: () => AgentNotFoundError,
   AuthenticationCredentialsRejectedError: () => AuthenticationCredentialsRejectedError,
   AuthenticationRequiredError: () => AuthenticationRequiredError,
+  BuyerSetupError: () => BuyerSetupError,
   ConfigurationError: () => ConfigurationError,
   DeferredTaskError: () => DeferredTaskError,
   FeatureUnsupportedError: () => FeatureUnsupportedError,
@@ -53,6 +58,7 @@ __export(errors_exports, {
   mapSdkErrorCodeToProtocolErrorCode: () => mapSdkErrorCodeToProtocolErrorCode
 });
 module.exports = __toCommonJS(errors_exports);
+var import_enums = require('../types/enums.generated.js');
 class ADCPError extends Error {
   constructor(message, details) {
     super(message);
@@ -160,6 +166,7 @@ class AccountRequiredError extends ADCPError {
   accountModel;
   taskName;
   code = "ACCOUNT_REQUIRED";
+  fault = "buyer_setup";
 }
 class AccountPendingApprovalError extends ADCPError {
   constructor(account, accountId) {
@@ -171,6 +178,7 @@ class AccountPendingApprovalError extends ADCPError {
   account;
   accountId;
   code = "ACCOUNT_PENDING_APPROVAL";
+  fault = "buyer_setup";
 }
 class AccountAmbiguousError extends ADCPError {
   constructor(candidates) {
@@ -181,6 +189,36 @@ class AccountAmbiguousError extends ADCPError {
   candidates;
   code = "ACCOUNT_AMBIGUOUS";
 }
+class BuyerSetupError extends ADCPError {
+  fault = "buyer_setup";
+}
+class AccountNotFoundError extends BuyerSetupError {
+  code = "ACCOUNT_NOT_FOUND";
+  constructor(message = "The account has not been provisioned at this seller.") {
+    super(message);
+  }
+}
+class AccountSetupRequiredError extends BuyerSetupError {
+  code = "ACCOUNT_SETUP_REQUIRED";
+  constructor(message = "Complete account setup before making account-scoped requests.") {
+    super(message);
+  }
+}
+class AccountPaymentRequiredError extends BuyerSetupError {
+  code = "ACCOUNT_PAYMENT_REQUIRED";
+  constructor(message = "Complete account payment before making account-scoped requests.") {
+    super(message);
+  }
+}
+class AccountNotProvisionedError extends AccountNotFoundError {
+  constructor(account, taskName) {
+    super(`${taskName} requires an account provisioned at this seller. Call client.accounts.ensure first.`);
+    this.account = account;
+    this.taskName = taskName;
+  }
+  account;
+  taskName;
+}
 class ProtocolError extends ADCPError {
   constructor(protocol, message, originalError) {
     super(`${protocol.toUpperCase()} protocol error: ${message}`);
@@ -236,13 +274,21 @@ class ConfigurationError extends ADCPError {
   code = "CONFIGURATION_ERROR";
 }
 class AuthenticationRequiredError extends ADCPError {
-  constructor(agentUrl, oauthMetadata, message, challenge) {
-    const defaultMessage = buildAuthRequiredMessage(agentUrl, oauthMetadata, challenge);
+  constructor(agentUrl, oauthMetadata, message, challenge, signedRejection) {
+    const defaultMessage = buildAuthRequiredMessage(agentUrl, oauthMetadata, challenge, !!signedRejection);
     super(message || defaultMessage);
     this.agentUrl = agentUrl;
     this.oauthMetadata = oauthMetadata;
     this.challenge = challenge;
     this.details = { agentUrl, oauthMetadata, challenge };
+    if (signedRejection) {
+      this.requestSigned = true;
+      this.status = signedRejection.status;
+      const signatureCode = getRequestSignatureRejectionCode(challenge);
+      if (signatureCode) this.signatureErrorCode = signatureCode;
+      Object.defineProperty(this, "responseBody", { value: signedRejection.responseBody, enumerable: false });
+      this.details = { agentUrl, challenge, requestSigned: true, status: this.status };
+    }
   }
   agentUrl;
   oauthMetadata;
@@ -300,7 +346,12 @@ function sanitizeAgentUrlForError(value) {
     return "invalid_url";
   }
 }
-function buildAuthRequiredMessage(agentUrl, oauthMetadata, challenge) {
+function buildAuthRequiredMessage(agentUrl, oauthMetadata, challenge, requestSigned = false) {
+  if (requestSigned || challenge?.scheme === "signature") {
+    const code = getRequestSignatureRejectionCode(challenge);
+    const suggestion = code ? ` ${import_enums.RequestSigningErrorCodeMetadata[code].suggestion}.` : "";
+    return `Authentication failed with HTTP 401 for ${sanitizeAgentUrlForError(agentUrl)}. ` + (requestSigned ? "The seller rejected an SDK-signed request" : "The seller requires a valid request signature") + (code ? ` (${code})` : "") + ". Check signature verification and key discovery (brand_json_url \u2192 agents[] \u2192 jwks_uri)." + (requestSigned && !challenge ? " No authentication challenge was returned; check configured credentials too." : "") + suggestion + (requestSigned ? " A bounded seller diagnostic is available on responseBody when captured." : "");
+  }
   if (challenge && challenge.scheme !== "bearer") {
     if (challenge.scheme === "basic") {
       return `Authentication required for ${agentUrl}. Agent (or its fronting gateway) speaks HTTP Basic (RFC 7617). Configure via createTestClient({ auth: { type: 'basic', username, password } }) \u2014 or from the CLI, --auth <user:pass> --auth-scheme basic.`;
@@ -313,6 +364,10 @@ function buildAuthRequiredMessage(agentUrl, oauthMetadata, challenge) {
   }
   return `Authentication required for ${agentUrl}. No OAuth metadata available - provide auth_token in agent config.`;
 }
+function getRequestSignatureRejectionCode(challenge) {
+  if (challenge?.scheme !== "signature" || !challenge.error) return void 0;
+  return Object.prototype.hasOwnProperty.call(import_enums.RequestSigningErrorCodeMetadata, challenge.error) ? challenge.error : void 0;
+}
 class IdempotencyConflictError extends ADCPError {
   code = "IDEMPOTENCY_CONFLICT";
   // Exposed via the getter so `console.log(err)` and JSON.stringify don't
@@ -518,6 +573,12 @@ function is401Error(error, got401Flag = false) {
 }
 function adcpErrorToTypedError(adcpError, idempotencyKey) {
   switch (adcpError.code) {
+    case "ACCOUNT_NOT_FOUND":
+      return new AccountNotFoundError(adcpError.message);
+    case "ACCOUNT_SETUP_REQUIRED":
+      return new AccountSetupRequiredError(adcpError.message);
+    case "ACCOUNT_PAYMENT_REQUIRED":
+      return new AccountPaymentRequiredError(adcpError.message);
     case "IDEMPOTENCY_CONFLICT":
       return new IdempotencyConflictError(idempotencyKey, adcpError.message);
     case "IDEMPOTENCY_EXPIRED":
@@ -596,12 +657,17 @@ function extractErrorInfo(error) {
 0 && (module.exports = {
   ADCPError,
   AccountAmbiguousError,
+  AccountNotFoundError,
+  AccountNotProvisionedError,
+  AccountPaymentRequiredError,
   AccountPendingApprovalError,
   AccountRequiredError,
+  AccountSetupRequiredError,
   ActionNotAllowedError,
   AgentNotFoundError,
   AuthenticationCredentialsRejectedError,
   AuthenticationRequiredError,
+  BuyerSetupError,
   ConfigurationError,
   DeferredTaskError,
   FeatureUnsupportedError,

package/dist/lib/errors/index.mjs

@@ -1,3 +1,4 @@
+import { RequestSigningErrorCodeMetadata } from "../types/enums.generated.mjs";
 class ADCPError extends Error {
   constructor(message, details) {
     super(message);
@@ -105,6 +106,7 @@ class AccountRequiredError extends ADCPError {
   accountModel;
   taskName;
   code = "ACCOUNT_REQUIRED";
+  fault = "buyer_setup";
 }
 class AccountPendingApprovalError extends ADCPError {
   constructor(account, accountId) {
@@ -116,6 +118,7 @@ class AccountPendingApprovalError extends ADCPError {
   account;
   accountId;
   code = "ACCOUNT_PENDING_APPROVAL";
+  fault = "buyer_setup";
 }
 class AccountAmbiguousError extends ADCPError {
   constructor(candidates) {
@@ -126,6 +129,36 @@ class AccountAmbiguousError extends ADCPError {
   candidates;
   code = "ACCOUNT_AMBIGUOUS";
 }
+class BuyerSetupError extends ADCPError {
+  fault = "buyer_setup";
+}
+class AccountNotFoundError extends BuyerSetupError {
+  code = "ACCOUNT_NOT_FOUND";
+  constructor(message = "The account has not been provisioned at this seller.") {
+    super(message);
+  }
+}
+class AccountSetupRequiredError extends BuyerSetupError {
+  code = "ACCOUNT_SETUP_REQUIRED";
+  constructor(message = "Complete account setup before making account-scoped requests.") {
+    super(message);
+  }
+}
+class AccountPaymentRequiredError extends BuyerSetupError {
+  code = "ACCOUNT_PAYMENT_REQUIRED";
+  constructor(message = "Complete account payment before making account-scoped requests.") {
+    super(message);
+  }
+}
+class AccountNotProvisionedError extends AccountNotFoundError {
+  constructor(account, taskName) {
+    super(`${taskName} requires an account provisioned at this seller. Call client.accounts.ensure first.`);
+    this.account = account;
+    this.taskName = taskName;
+  }
+  account;
+  taskName;
+}
 class ProtocolError extends ADCPError {
   constructor(protocol, message, originalError) {
     super(`${protocol.toUpperCase()} protocol error: ${message}`);
@@ -181,13 +214,21 @@ class ConfigurationError extends ADCPError {
   code = "CONFIGURATION_ERROR";
 }
 class AuthenticationRequiredError extends ADCPError {
-  constructor(agentUrl, oauthMetadata, message, challenge) {
-    const defaultMessage = buildAuthRequiredMessage(agentUrl, oauthMetadata, challenge);
+  constructor(agentUrl, oauthMetadata, message, challenge, signedRejection) {
+    const defaultMessage = buildAuthRequiredMessage(agentUrl, oauthMetadata, challenge, !!signedRejection);
     super(message || defaultMessage);
     this.agentUrl = agentUrl;
     this.oauthMetadata = oauthMetadata;
     this.challenge = challenge;
     this.details = { agentUrl, oauthMetadata, challenge };
+    if (signedRejection) {
+      this.requestSigned = true;
+      this.status = signedRejection.status;
+      const signatureCode = getRequestSignatureRejectionCode(challenge);
+      if (signatureCode) this.signatureErrorCode = signatureCode;
+      Object.defineProperty(this, "responseBody", { value: signedRejection.responseBody, enumerable: false });
+      this.details = { agentUrl, challenge, requestSigned: true, status: this.status };
+    }
   }
   agentUrl;
   oauthMetadata;
@@ -245,7 +286,12 @@ function sanitizeAgentUrlForError(value) {
     return "invalid_url";
   }
 }
-function buildAuthRequiredMessage(agentUrl, oauthMetadata, challenge) {
+function buildAuthRequiredMessage(agentUrl, oauthMetadata, challenge, requestSigned = false) {
+  if (requestSigned || challenge?.scheme === "signature") {
+    const code = getRequestSignatureRejectionCode(challenge);
+    const suggestion = code ? ` ${RequestSigningErrorCodeMetadata[code].suggestion}.` : "";
+    return `Authentication failed with HTTP 401 for ${sanitizeAgentUrlForError(agentUrl)}. ` + (requestSigned ? "The seller rejected an SDK-signed request" : "The seller requires a valid request signature") + (code ? ` (${code})` : "") + ". Check signature verification and key discovery (brand_json_url \u2192 agents[] \u2192 jwks_uri)." + (requestSigned && !challenge ? " No authentication challenge was returned; check configured credentials too." : "") + suggestion + (requestSigned ? " A bounded seller diagnostic is available on responseBody when captured." : "");
+  }
   if (challenge && challenge.scheme !== "bearer") {
     if (challenge.scheme === "basic") {
       return `Authentication required for ${agentUrl}. Agent (or its fronting gateway) speaks HTTP Basic (RFC 7617). Configure via createTestClient({ auth: { type: 'basic', username, password } }) \u2014 or from the CLI, --auth <user:pass> --auth-scheme basic.`;
@@ -258,6 +304,10 @@ function buildAuthRequiredMessage(agentUrl, oauthMetadata, challenge) {
   }
   return `Authentication required for ${agentUrl}. No OAuth metadata available - provide auth_token in agent config.`;
 }
+function getRequestSignatureRejectionCode(challenge) {
+  if (challenge?.scheme !== "signature" || !challenge.error) return void 0;
+  return Object.prototype.hasOwnProperty.call(RequestSigningErrorCodeMetadata, challenge.error) ? challenge.error : void 0;
+}
 class IdempotencyConflictError extends ADCPError {
   code = "IDEMPOTENCY_CONFLICT";
   // Exposed via the getter so `console.log(err)` and JSON.stringify don't
@@ -463,6 +513,12 @@ function is401Error(error, got401Flag = false) {
 }
 function adcpErrorToTypedError(adcpError, idempotencyKey) {
   switch (adcpError.code) {
+    case "ACCOUNT_NOT_FOUND":
+      return new AccountNotFoundError(adcpError.message);
+    case "ACCOUNT_SETUP_REQUIRED":
+      return new AccountSetupRequiredError(adcpError.message);
+    case "ACCOUNT_PAYMENT_REQUIRED":
+      return new AccountPaymentRequiredError(adcpError.message);
     case "IDEMPOTENCY_CONFLICT":
       return new IdempotencyConflictError(idempotencyKey, adcpError.message);
     case "IDEMPOTENCY_EXPIRED":
@@ -540,12 +596,17 @@ function extractErrorInfo(error) {
 export {
   ADCPError,
   AccountAmbiguousError,
+  AccountNotFoundError,
+  AccountNotProvisionedError,
+  AccountPaymentRequiredError,
   AccountPendingApprovalError,
   AccountRequiredError,
+  AccountSetupRequiredError,
   ActionNotAllowedError,
   AgentNotFoundError,
   AuthenticationCredentialsRejectedError,
   AuthenticationRequiredError,
+  BuyerSetupError,
   ConfigurationError,
   DeferredTaskError,
   FeatureUnsupportedError,

package/dist/lib/governance/authorization.d.mts

@@ -12,6 +12,7 @@ import type { CheckGovernanceRequest, GovernancePhase, PlannedDelivery } from '.
 import type { JwksResolver } from '../signing/jwks.mjs';
 import type { ReplayStore } from '../signing/replay.mjs';
 import type { RevocationStore } from '../signing/revocation.mjs';
+import { type HttpsJwksResolverOptions } from '../signing/jwks-https.mjs';
 export declare const GOVERNANCE_AUTHORIZATION_CRITICAL_CLAIMS: readonly ["authorized_commitment", "authorized_task", "authorized_payload_hash"];
 export type GovernanceAuthorizationCriticalClaim = (typeof GOVERNANCE_AUTHORIZATION_CRITICAL_CLAIMS)[number];
 export type GovernanceEnforcementMode = 'signed_context' | 'online_execution_check';
@@ -101,6 +102,18 @@ export interface GovernanceRevocationStatus {
 export interface GovernanceRevocationResolver {
     resolve(issuer: string, kid: string, jti: string): GovernanceRevocationStatus | Promise<GovernanceRevocationStatus>;
 }
+/** Authenticated buyer context, never the JWS payload or a sibling brand's record. */
+export interface GovernanceBuyerIdentity {
+    /** For signed buyers, pass AgentResolution.brandJson without refetching its host. */
+    brandJson: unknown;
+    /** Domain of the governed request's brand; portfolio brands require an exact URL hostname match (including www). */
+    brandDomain: string;
+    /** Trusted resolver factory; implementations may cache by canonical JWKS URI. */
+    jwksForUri?: (jwksUri: string) => JwksResolver;
+    /** Reuse this options object across requests to share its bounded resolver cache. */
+    jwksOptions?: HttpsJwksResolverOptions;
+}
+export declare function createGovernanceAgentJwksResolver(issuer: string, buyer: GovernanceBuyerIdentity): JwksResolver;
 export interface VerifyGovernanceAuthorizationOptions {
     token: unknown;
     expectedIssuer: string;
@@ -111,7 +124,9 @@ export interface VerifyGovernanceAuthorizationOptions {
     actualCommitment: GovernanceCommitment;
     /** Defaults to `intent`, the phase accepted by a downstream service. */
     expectedPhase?: 'intent';
-    jwks: JwksResolver;
+    jwks?: JwksResolver;
+    /** When supplied, discover keys from this exact authenticated buyer record. */
+    buyerIdentity?: GovernanceBuyerIdentity;
     replayStore: GovernanceReplayStore;
     /** Optional governance-key revocation source. */
     revocationStore?: RevocationStore;
@@ -178,6 +193,7 @@ export declare class GovernanceAuthorizationError extends Error {
 }
 export interface GovernanceEnforcementMiddlewareInput {
     token: unknown;
+    buyerIdentity?: GovernanceBuyerIdentity;
     authenticatedCaller: string;
     task: string;
     payload: Record<string, unknown>;

package/dist/lib/governance/authorization.d.ts

@@ -12,6 +12,7 @@ import type { CheckGovernanceRequest, GovernancePhase, PlannedDelivery } from '.
 import type { JwksResolver } from '../signing/jwks';
 import type { ReplayStore } from '../signing/replay';
 import type { RevocationStore } from '../signing/revocation';
+import { type HttpsJwksResolverOptions } from '../signing/jwks-https';
 export declare const GOVERNANCE_AUTHORIZATION_CRITICAL_CLAIMS: readonly ["authorized_commitment", "authorized_task", "authorized_payload_hash"];
 export type GovernanceAuthorizationCriticalClaim = (typeof GOVERNANCE_AUTHORIZATION_CRITICAL_CLAIMS)[number];
 export type GovernanceEnforcementMode = 'signed_context' | 'online_execution_check';
@@ -101,6 +102,18 @@ export interface GovernanceRevocationStatus {
 export interface GovernanceRevocationResolver {
     resolve(issuer: string, kid: string, jti: string): GovernanceRevocationStatus | Promise<GovernanceRevocationStatus>;
 }
+/** Authenticated buyer context, never the JWS payload or a sibling brand's record. */
+export interface GovernanceBuyerIdentity {
+    /** For signed buyers, pass AgentResolution.brandJson without refetching its host. */
+    brandJson: unknown;
+    /** Domain of the governed request's brand; portfolio brands require an exact URL hostname match (including www). */
+    brandDomain: string;
+    /** Trusted resolver factory; implementations may cache by canonical JWKS URI. */
+    jwksForUri?: (jwksUri: string) => JwksResolver;
+    /** Reuse this options object across requests to share its bounded resolver cache. */
+    jwksOptions?: HttpsJwksResolverOptions;
+}
+export declare function createGovernanceAgentJwksResolver(issuer: string, buyer: GovernanceBuyerIdentity): JwksResolver;
 export interface VerifyGovernanceAuthorizationOptions {
     token: unknown;
     expectedIssuer: string;
@@ -111,7 +124,9 @@ export interface VerifyGovernanceAuthorizationOptions {
     actualCommitment: GovernanceCommitment;
     /** Defaults to `intent`, the phase accepted by a downstream service. */
     expectedPhase?: 'intent';
-    jwks: JwksResolver;
+    jwks?: JwksResolver;
+    /** When supplied, discover keys from this exact authenticated buyer record. */
+    buyerIdentity?: GovernanceBuyerIdentity;
     replayStore: GovernanceReplayStore;
     /** Optional governance-key revocation source. */
     revocationStore?: RevocationStore;
@@ -178,6 +193,7 @@ export declare class GovernanceAuthorizationError extends Error {
 }
 export interface GovernanceEnforcementMiddlewareInput {
     token: unknown;
+    buyerIdentity?: GovernanceBuyerIdentity;
     authenticatedCaller: string;
     task: string;
     payload: Record<string, unknown>;