@adcp/sdk 14.0.0-rc.41 → 14.0.0-rc.42

package/dist/lib/core/AgentClient.d.ts

@@ -2,7 +2,7 @@ import type { Client as MCPClient } from '@modelcontextprotocol/sdk/client/index
 import type { AgentConfig } from '../types';
 import type { MCPWebhookPayload, GetBrandIdentityRequest, GetBrandIdentityResponse, ContextMatchRequest, ContextMatchResponse, IdentityMatchRequest, IdentityMatchResponseRouterPublisher } from '../types/core.generated';
 import type { Task as A2ATask, TaskStatusUpdateEvent } from '@a2a-js/sdk';
-import { type CanonicalReadTaskOptions, type CreativeDeliveryTaskOptions, type SingleAgentClientConfig, type SyncCreativesTaskOptions, type VerifyAndParseWebhookOptions, type WebhookHandlerAdapter, type WebhookParseResult, type WebhookRequestContext } from './SingleAgentClient';
+import { type CapabilityEvidenceScope, type CapabilityEvidenceSnapshot, type CanonicalReadTaskOptions, type CreativeDeliveryTaskOptions, type SingleAgentClientConfig, type SyncCreativesTaskOptions, type VerifyAndParseWebhookOptions, type WebhookHandlerAdapter, type WebhookParseResult, type WebhookRequestContext } from './SingleAgentClient';
 import type { InputHandler, TaskOptions, TaskResult, TaskInfo, Message, DirectPauseRecoveryRequest } from './ConversationTypes';
 import type { AdcpCapabilities } from '../utils/capabilities';
 import type { WebhookHeaderValue } from '../webhooks';
@@ -167,6 +167,22 @@ export type InProcessAgentClientConfig = Pick<SingleAgentClientConfig, 'adcpVers
      */
     agentId?: string;
 };
+/** Context passed to {@link AgentClient.createWithCapabilityPreflight}. */
+export interface CapabilityPreflightContext {
+    /** The exact client instance that will be returned by the factory. */
+    client: AgentClient;
+    /** Opaque authorization/transport scope the returned snapshot must carry. */
+    scope: CapabilityEvidenceScope;
+}
+/** Load or perform capability discovery for one newly constructed client. */
+export type CapabilityPreflightLoader = (context: CapabilityPreflightContext) => CapabilityEvidenceSnapshot | Promise<CapabilityEvidenceSnapshot>;
+export type CapabilityPreflightErrorCode = 'scoped_transport' | 'scope_rotated' | 'invalid_evidence';
+/** Actionable factory failure without weakening the same-instance invariant. */
+export declare class CapabilityPreflightError extends Error {
+    readonly code: CapabilityPreflightErrorCode;
+    readonly name = "CapabilityPreflightError";
+    constructor(code: CapabilityPreflightErrorCode, message: string);
+}
 export declare class AgentClient {
     private agent;
     private config;
@@ -176,6 +192,16 @@ export declare class AgentClient {
     private readonly sessionTrackedDeferredContinuations;
     private readonly _isInProcess;
     constructor(agent: AgentConfig, config?: SingleAgentClientConfig);
+    /**
+     * Construct and prime one client before exposing it for task dispatch.
+     *
+     * Capability evidence is intentionally bound to a client instance. This
+     * factory gives application factories the instance and its opaque scope
+     * before the first task can be sent, then installs the callback's snapshot
+     * on that same instance. Evidence from an otherwise identical client is
+     * rejected rather than silently falling back to redundant discovery.
+     */
+    static createWithCapabilityPreflight(agent: AgentConfig, loadEvidence: CapabilityPreflightLoader, config?: SingleAgentClientConfig): Promise<AgentClient>;
     /**
      * Recover the current A2A pause generation for a direct mutation that opted
      * into `TaskOptions.durableContinuationRecovery`.

package/dist/lib/core/AgentClient.js

@@ -18,7 +18,8 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var AgentClient_exports = {};
 __export(AgentClient_exports, {
-  AgentClient: () => AgentClient
+  AgentClient: () => AgentClient,
+  CapabilityPreflightError: () => CapabilityPreflightError
 });
 module.exports = __toCommonJS(AgentClient_exports);
 var import_node_crypto = require("node:crypto");
@@ -33,6 +34,14 @@ function stripRefineProposalsSdkAnnotations(data) {
   delete canonical._message;
   return canonical;
 }
+class CapabilityPreflightError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+  code;
+  name = "CapabilityPreflightError";
+}
 const NON_TERMINAL_STATES = /* @__PURE__ */ new Set([
   "working",
   "input-required",
@@ -54,6 +63,35 @@ class AgentClient {
   pendingTask;
   sessionTrackedDeferredContinuations = /* @__PURE__ */ new WeakSet();
   _isInProcess;
+  /**
+   * Construct and prime one client before exposing it for task dispatch.
+   *
+   * Capability evidence is intentionally bound to a client instance. This
+   * factory gives application factories the instance and its opaque scope
+   * before the first task can be sent, then installs the callback's snapshot
+   * on that same instance. Evidence from an otherwise identical client is
+   * rejected rather than silently falling back to redundant discovery.
+   */
+  static async createWithCapabilityPreflight(agent, loadEvidence, config = {}) {
+    const client = new AgentClient(agent, config);
+    if (config.transport?.trustedFetchFn || config.transport?.fetchFn) {
+      throw new CapabilityPreflightError(
+        "scoped_transport",
+        "AgentClient.createWithCapabilityPreflight cannot prime a client configured with transport.trustedFetchFn. Keep the scoped transport: construct AgentClient normally so capability discovery runs inside that transport scope."
+      );
+    }
+    const scope = client.getCapabilityEvidenceScope();
+    const snapshot = await loadEvidence({ client, scope });
+    if (!client.primeCapabilities(snapshot)) {
+      const currentScope = client.getCapabilityEvidenceScope();
+      const scopeRotated = currentScope.scopeKey !== scope.scopeKey && snapshot?.scope?.scopeKey !== currentScope.scopeKey;
+      throw new CapabilityPreflightError(
+        scopeRotated ? "scope_rotated" : "invalid_evidence",
+        scopeRotated ? "AgentClient.createWithCapabilityPreflight: authorization changed while capability evidence was loading. Repeat preflight with the client's current scope, or construct normally to perform cold discovery." : "AgentClient.createWithCapabilityPreflight: evidence was stale, malformed, missing tool evidence, or scoped to another client. Return a fresh snapshot carrying the callback scope; otherwise construct normally to perform cold discovery."
+      );
+    }
+    return client;
+  }
   /**
    * Internal access to the underlying `TaskExecutor`. Used by the storyboard
    * runner's `pollTaskCompletion` race so it can poll AdCP `tasks/get` against
@@ -1306,5 +1344,6 @@ class AgentClient {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  AgentClient
+  AgentClient,
+  CapabilityPreflightError
 });

package/dist/lib/core/AgentClient.mjs

@@ -12,6 +12,14 @@ function stripRefineProposalsSdkAnnotations(data) {
   delete canonical._message;
   return canonical;
 }
+class CapabilityPreflightError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+  code;
+  name = "CapabilityPreflightError";
+}
 const NON_TERMINAL_STATES = /* @__PURE__ */ new Set([
   "working",
   "input-required",
@@ -33,6 +41,35 @@ class AgentClient {
   pendingTask;
   sessionTrackedDeferredContinuations = /* @__PURE__ */ new WeakSet();
   _isInProcess;
+  /**
+   * Construct and prime one client before exposing it for task dispatch.
+   *
+   * Capability evidence is intentionally bound to a client instance. This
+   * factory gives application factories the instance and its opaque scope
+   * before the first task can be sent, then installs the callback's snapshot
+   * on that same instance. Evidence from an otherwise identical client is
+   * rejected rather than silently falling back to redundant discovery.
+   */
+  static async createWithCapabilityPreflight(agent, loadEvidence, config = {}) {
+    const client = new AgentClient(agent, config);
+    if (config.transport?.trustedFetchFn || config.transport?.fetchFn) {
+      throw new CapabilityPreflightError(
+        "scoped_transport",
+        "AgentClient.createWithCapabilityPreflight cannot prime a client configured with transport.trustedFetchFn. Keep the scoped transport: construct AgentClient normally so capability discovery runs inside that transport scope."
+      );
+    }
+    const scope = client.getCapabilityEvidenceScope();
+    const snapshot = await loadEvidence({ client, scope });
+    if (!client.primeCapabilities(snapshot)) {
+      const currentScope = client.getCapabilityEvidenceScope();
+      const scopeRotated = currentScope.scopeKey !== scope.scopeKey && snapshot?.scope?.scopeKey !== currentScope.scopeKey;
+      throw new CapabilityPreflightError(
+        scopeRotated ? "scope_rotated" : "invalid_evidence",
+        scopeRotated ? "AgentClient.createWithCapabilityPreflight: authorization changed while capability evidence was loading. Repeat preflight with the client's current scope, or construct normally to perform cold discovery." : "AgentClient.createWithCapabilityPreflight: evidence was stale, malformed, missing tool evidence, or scoped to another client. Return a fresh snapshot carrying the callback scope; otherwise construct normally to perform cold discovery."
+      );
+    }
+    return client;
+  }
   /**
    * Internal access to the underlying `TaskExecutor`. Used by the storyboard
    * runner's `pollTaskCompletion` race so it can poll AdCP `tasks/get` against
@@ -1284,5 +1321,6 @@ class AgentClient {
   }
 }
 export {
-  AgentClient
+  AgentClient,
+  CapabilityPreflightError
 };

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

@@ -378,7 +378,7 @@ export type ActionNotAllowedReasonValue = 'wrong_status' | 'not_supported_on_pro
 export type ActionNotAllowedAttemptedAction = string;
 export interface ActionNotAllowedAvailableAction {
     action: ActionNotAllowedAttemptedAction;
-    mode: 'self_serve' | 'conditional_self_serve' | 'requires_proposal' | 'requires_approval';
+    mode: 'self_serve' | 'conditional_self_serve' | 'seller_managed' | 'requires_proposal' | 'requires_approval';
     sla?: unknown;
     terms_ref?: string;
 }
@@ -388,6 +388,9 @@ export type ActionNotAllowedRecovery = {
 } | {
     kind: 'waitForApproval';
     message: string;
+} | {
+    kind: 'waitForTask';
+    message: string;
 } | {
     kind: 'reissueAsDirect';
     message: string;

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

@@ -378,7 +378,7 @@ export type ActionNotAllowedReasonValue = 'wrong_status' | 'not_supported_on_pro
 export type ActionNotAllowedAttemptedAction = string;
 export interface ActionNotAllowedAvailableAction {
     action: ActionNotAllowedAttemptedAction;
-    mode: 'self_serve' | 'conditional_self_serve' | 'requires_proposal' | 'requires_approval';
+    mode: 'self_serve' | 'conditional_self_serve' | 'seller_managed' | 'requires_proposal' | 'requires_approval';
     sla?: unknown;
     terms_ref?: string;
 }
@@ -388,6 +388,9 @@ export type ActionNotAllowedRecovery = {
 } | {
     kind: 'waitForApproval';
     message: string;
+} | {
+    kind: 'waitForTask';
+    message: string;
 } | {
     kind: 'reissueAsDirect';
     message: string;

package/dist/lib/errors/index.js

@@ -396,6 +396,11 @@ function buildModeMismatchRecovery(details) {
   const match = details.currently_available_actions?.find((a) => a.action === details.attempted_action);
   if (!match) return void 0;
   switch (match.mode) {
+    case "seller_managed":
+      return {
+        kind: "waitForTask",
+        message: "Use the declared task and follow its submitted/working/completed lifecycle."
+      };
     case "requires_proposal":
       return {
         kind: "createProposal",
@@ -508,7 +513,7 @@ function isActionNotAllowedReason(value) {
   return value === "wrong_status" || value === "not_supported_on_product" || value === "not_supported_on_buy" || value === "mode_mismatch";
 }
 function isActionMode(value) {
-  return value === "self_serve" || value === "conditional_self_serve" || value === "requires_proposal" || value === "requires_approval";
+  return value === "self_serve" || value === "conditional_self_serve" || value === "seller_managed" || value === "requires_proposal" || value === "requires_approval";
 }
 function isADCPError(error) {
   return error instanceof ADCPError;

package/dist/lib/errors/index.mjs

@@ -345,6 +345,11 @@ function buildModeMismatchRecovery(details) {
   const match = details.currently_available_actions?.find((a) => a.action === details.attempted_action);
   if (!match) return void 0;
   switch (match.mode) {
+    case "seller_managed":
+      return {
+        kind: "waitForTask",
+        message: "Use the declared task and follow its submitted/working/completed lifecycle."
+      };
     case "requires_proposal":
       return {
         kind: "createProposal",
@@ -457,7 +462,7 @@ function isActionNotAllowedReason(value) {
   return value === "wrong_status" || value === "not_supported_on_product" || value === "not_supported_on_buy" || value === "mode_mismatch";
 }
 function isActionMode(value) {
-  return value === "self_serve" || value === "conditional_self_serve" || value === "requires_proposal" || value === "requires_approval";
+  return value === "self_serve" || value === "conditional_self_serve" || value === "seller_managed" || value === "requires_proposal" || value === "requires_approval";
 }
 function isADCPError(error) {
   return error instanceof ADCPError;

package/dist/lib/index.d.mts

@@ -19,7 +19,7 @@ export { InMemoryWebhookRegistrationStore, type InMemoryWebhookRegistrationStore
 export { pgWebhookRegistrationStore, getWebhookRegistrationMigration, WEBHOOK_REGISTRATION_MIGRATION, cleanupExpiredWebhookRegistrations, type PgWebhookRegistrationStoreOptions, type CleanupExpiredWebhookRegistrationsOptions, } from './core/postgres-webhook-registration-store.mjs';
 export { redisWebhookRegistrationStore, type RedisWebhookRegistrationStoreOptions, } from './core/redis-webhook-registration-store.mjs';
 export type { DelegatedOperatorAuthorizationContext } from './signing/agent-resolver/index.mjs';
-export { AgentClient, type CanonicalGetProductsResponse, type CanonicalProjectionTaskOptions, type ProposalRefinementTaskOptions, type TaskResponseTypeMap, type TaskRequestTypeMap, type TaskRequestFor, type AdcpTaskName, type InProcessAgentClientConfig, } from './core/AgentClient.mjs';
+export { AgentClient, CapabilityPreflightError, type CanonicalGetProductsResponse, type CanonicalProjectionTaskOptions, type ProposalRefinementTaskOptions, type TaskResponseTypeMap, type TaskRequestTypeMap, type TaskRequestFor, type AdcpTaskName, type CapabilityPreflightContext, type CapabilityPreflightErrorCode, type CapabilityPreflightLoader, type InProcessAgentClientConfig, } from './core/AgentClient.mjs';
 export { MediaBuyLifecycleCoordinator, MediaBuyLifecycleCompatibilityError, LegacyPurchaseContinuationError, negotiateMediaBuyLifecycle, type CompatibleDeclineProposalsResponse, type CompatibleDeclineProposalsWireResponse, type CompatibleDeclineResult, type CompatibleProductsResponse, type CompatibleProductsWireResponse, type CompatibleProduct, type CompatibleProposal, type CompatibleProposalResponse, type CompatibleProjectedDeclineResult, type CompatibleRefinementResult, type CompatibleRefineProposalsResponse, type CompatibleRefineProposalsWireResponse, type CompatibleRequestProposalsResponse, type CompatibleRequestProposalsWireResponse, type CompatibleAcceptProposalRequest, type CompatibilityDeferredContinuation, type CompatibilitySubmittedContinuation, type CompatibilityTaskResult, type EstablishedProductsWireResponse, type EstablishedProposalAcceptanceFallback, type EstablishedProposalTaskReconciliationInput, type MediaBuyCompatibility, type MediaBuyCompatibilityLoss, type MediaBuyCompatibilityReport, type MediaBuyLifecycle, type MediaBuyLifecycleCoordinatorOptions, type LegacyPurchaseContinuationErrorCode, } from './media-buy/compatibility.mjs';
 export { InMemoryLegacyPurchaseContinuationStore, createInMemoryLegacyPurchaseContinuationStore, LEGACY_PURCHASE_PUBLICATION_PROOF_RETENTION_MS, legacyPurchaseSettlementFingerprint, type InMemoryLegacyPurchaseContinuationStoreOptions, type LegacyPurchaseBinding, type LegacyPurchaseClaim, type LegacyPurchaseClaimRequest, type LegacyPurchaseClaimResult, type LegacyPurchaseCompleteResult, type LegacyPurchaseContinuationRecord, type LegacyPurchaseContinuationStore, type LegacyPurchaseCreateResult, type LegacyPurchaseLoss, type LegacyPurchaseOperation, type LegacyPurchasePendingSettlement, type LegacyPurchasePendingSettlementResult, type LegacyPurchasePublicationLease, type LegacyPurchaseReconciliationResult, type LegacyPurchaseSourceVersion, type LegacyPurchaseTerminalResult, type ReconcileLegacyPurchase, } from './media-buy/legacy-purchase-continuation.mjs';
 export { InMemoryEstablishedProposalStore, createInMemoryEstablishedProposalStore, ESTABLISHED_PROPOSAL_COMPLETION_TOMBSTONE_RETENTION_MS, type EstablishedProposalBinding, type EstablishedProposalCompletionWindow, type EstablishedProposalMutationClaim, type EstablishedProposalMutationBinding, type EstablishedProposalMutationIntent, type EstablishedProposalMutationDisposition, type EstablishedProposalMutationKind, type EstablishedProposalOperation, type EstablishedProposalPutResult, type EstablishedProposalRecord, type EstablishedProposalReserveRequest, type EstablishedProposalReserveResult, type EstablishedProposalScope, type EstablishedProposalSourceVersion, type EstablishedProposalStore, type EstablishedProposalSubmittedOperation, type EstablishedProposalTaskScope, type EstablishedProposalTransitionResult, type InMemoryEstablishedProposalStoreOptions, type ProposalSnapshotEntry, } from './media-buy/established-proposal-store.mjs';

package/dist/lib/index.d.ts

@@ -19,7 +19,7 @@ export { InMemoryWebhookRegistrationStore, type InMemoryWebhookRegistrationStore
 export { pgWebhookRegistrationStore, getWebhookRegistrationMigration, WEBHOOK_REGISTRATION_MIGRATION, cleanupExpiredWebhookRegistrations, type PgWebhookRegistrationStoreOptions, type CleanupExpiredWebhookRegistrationsOptions, } from './core/postgres-webhook-registration-store';
 export { redisWebhookRegistrationStore, type RedisWebhookRegistrationStoreOptions, } from './core/redis-webhook-registration-store';
 export type { DelegatedOperatorAuthorizationContext } from './signing/agent-resolver';
-export { AgentClient, type CanonicalGetProductsResponse, type CanonicalProjectionTaskOptions, type ProposalRefinementTaskOptions, type TaskResponseTypeMap, type TaskRequestTypeMap, type TaskRequestFor, type AdcpTaskName, type InProcessAgentClientConfig, } from './core/AgentClient';
+export { AgentClient, CapabilityPreflightError, type CanonicalGetProductsResponse, type CanonicalProjectionTaskOptions, type ProposalRefinementTaskOptions, type TaskResponseTypeMap, type TaskRequestTypeMap, type TaskRequestFor, type AdcpTaskName, type CapabilityPreflightContext, type CapabilityPreflightErrorCode, type CapabilityPreflightLoader, type InProcessAgentClientConfig, } from './core/AgentClient';
 export { MediaBuyLifecycleCoordinator, MediaBuyLifecycleCompatibilityError, LegacyPurchaseContinuationError, negotiateMediaBuyLifecycle, type CompatibleDeclineProposalsResponse, type CompatibleDeclineProposalsWireResponse, type CompatibleDeclineResult, type CompatibleProductsResponse, type CompatibleProductsWireResponse, type CompatibleProduct, type CompatibleProposal, type CompatibleProposalResponse, type CompatibleProjectedDeclineResult, type CompatibleRefinementResult, type CompatibleRefineProposalsResponse, type CompatibleRefineProposalsWireResponse, type CompatibleRequestProposalsResponse, type CompatibleRequestProposalsWireResponse, type CompatibleAcceptProposalRequest, type CompatibilityDeferredContinuation, type CompatibilitySubmittedContinuation, type CompatibilityTaskResult, type EstablishedProductsWireResponse, type EstablishedProposalAcceptanceFallback, type EstablishedProposalTaskReconciliationInput, type MediaBuyCompatibility, type MediaBuyCompatibilityLoss, type MediaBuyCompatibilityReport, type MediaBuyLifecycle, type MediaBuyLifecycleCoordinatorOptions, type LegacyPurchaseContinuationErrorCode, } from './media-buy/compatibility';
 export { InMemoryLegacyPurchaseContinuationStore, createInMemoryLegacyPurchaseContinuationStore, LEGACY_PURCHASE_PUBLICATION_PROOF_RETENTION_MS, legacyPurchaseSettlementFingerprint, type InMemoryLegacyPurchaseContinuationStoreOptions, type LegacyPurchaseBinding, type LegacyPurchaseClaim, type LegacyPurchaseClaimRequest, type LegacyPurchaseClaimResult, type LegacyPurchaseCompleteResult, type LegacyPurchaseContinuationRecord, type LegacyPurchaseContinuationStore, type LegacyPurchaseCreateResult, type LegacyPurchaseLoss, type LegacyPurchaseOperation, type LegacyPurchasePendingSettlement, type LegacyPurchasePendingSettlementResult, type LegacyPurchasePublicationLease, type LegacyPurchaseReconciliationResult, type LegacyPurchaseSourceVersion, type LegacyPurchaseTerminalResult, type ReconcileLegacyPurchase, } from './media-buy/legacy-purchase-continuation';
 export { InMemoryEstablishedProposalStore, createInMemoryEstablishedProposalStore, ESTABLISHED_PROPOSAL_COMPLETION_TOMBSTONE_RETENTION_MS, type EstablishedProposalBinding, type EstablishedProposalCompletionWindow, type EstablishedProposalMutationClaim, type EstablishedProposalMutationBinding, type EstablishedProposalMutationIntent, type EstablishedProposalMutationDisposition, type EstablishedProposalMutationKind, type EstablishedProposalOperation, type EstablishedProposalPutResult, type EstablishedProposalRecord, type EstablishedProposalReserveRequest, type EstablishedProposalReserveResult, type EstablishedProposalScope, type EstablishedProposalSourceVersion, type EstablishedProposalStore, type EstablishedProposalSubmittedOperation, type EstablishedProposalTaskScope, type EstablishedProposalTransitionResult, type InMemoryEstablishedProposalStoreOptions, type ProposalSnapshotEntry, } from './media-buy/established-proposal-store';

package/dist/lib/index.js

@@ -57,6 +57,7 @@ __export(index_exports, {
   CREATIVE_ASSET_TRANSITIONS: () => import_server.CREATIVE_ASSET_TRANSITIONS,
   CREATIVE_TOOLS: () => import_capabilities.CREATIVE_TOOLS,
   CanonicalFormat: () => import_projection.CanonicalFormat,
+  CapabilityPreflightError: () => import_AgentClient.CapabilityPreflightError,
   ClientCredentialsExchangeError: () => import_oauth4.ClientCredentialsExchangeError,
   ConfigurationError: () => import_errors.ConfigurationError,
   ConfigurationManager: () => import_ConfigurationManager.ConfigurationManager,
@@ -868,6 +869,7 @@ function createAdCPClientFromEnv() {
   CREATIVE_ASSET_TRANSITIONS,
   CREATIVE_TOOLS,
   CanonicalFormat,
+  CapabilityPreflightError,
   ClientCredentialsExchangeError,
   ConfigurationError,
   ConfigurationManager,

package/dist/lib/index.mjs

@@ -88,7 +88,8 @@ import {
   redisWebhookRegistrationStore
 } from "./core/redis-webhook-registration-store.mjs";
 import {
-  AgentClient
+  AgentClient,
+  CapabilityPreflightError
 } from "./core/AgentClient.mjs";
 import {
   MediaBuyLifecycleCoordinator,
@@ -825,6 +826,7 @@ export {
   CREATIVE_ASSET_TRANSITIONS,
   CREATIVE_TOOLS,
   CanonicalFormat,
+  CapabilityPreflightError,
   ClientCredentialsExchangeError,
   ConfigurationError,
   ConfigurationManager,

package/dist/lib/media-buy/action-assessment.js

@@ -29,6 +29,7 @@ module.exports = __toCommonJS(action_assessment_exports);
 var import_action_contracts = require('./action-contracts.js');
 var import_action_constraints = require('./action-constraints.js');
 var import_mutations = require('./mutations.js');
+var import_available_actions = require('./available-actions.js');
 function assessProductAction(product, action) {
   if (product?.allowed_actions === void 0)
     return { status: "unknown", binding: false, message: "Product action information is absent." };
@@ -163,6 +164,12 @@ function assessActionAvailability(buy, action, options = {}) {
     return deny("condition_unresolved", "The deliberately emitted term aliases disagree.", "unknown");
   if (metadataOnly && entry.change_term_id !== void 0)
     return deny("condition_unresolved", "Metadata-only actions cannot identify a commercial change term.", "unknown");
+  if (entry.mode === import_available_actions.LEGACY_REQUIRES_PROPOSAL_MODE)
+    return deny(
+      "mode_mismatch",
+      "This unpublished legacy mode requires the proposal lifecycle; do not dispatch the mutation directly.",
+      "blocked"
+    );
   if (!["self_serve", "conditional_self_serve", "seller_managed", "requires_approval"].includes(entry.mode))
     return deny("condition_unresolved", "Unknown live action mode; refresh the seller declaration.", "unknown");
   if (term && (entry.mode !== term.service_mode || !(0, import_action_contracts.slaWithin)(term.processing_sla, entry.sla)))

package/dist/lib/media-buy/action-assessment.mjs

@@ -14,6 +14,7 @@ import {
 } from "./action-contracts.mjs";
 import { evaluateChangeTermConstraints } from "./action-constraints.mjs";
 import { decomposeUpdateMediaBuy, hasUnmappedMutation, mutationShapeIssue } from "./mutations.mjs";
+import { LEGACY_REQUIRES_PROPOSAL_MODE } from "./available-actions.mjs";
 function assessProductAction(product, action) {
   if (product?.allowed_actions === void 0)
     return { status: "unknown", binding: false, message: "Product action information is absent." };
@@ -148,6 +149,12 @@ function assessActionAvailability(buy, action, options = {}) {
     return deny("condition_unresolved", "The deliberately emitted term aliases disagree.", "unknown");
   if (metadataOnly && entry.change_term_id !== void 0)
     return deny("condition_unresolved", "Metadata-only actions cannot identify a commercial change term.", "unknown");
+  if (entry.mode === LEGACY_REQUIRES_PROPOSAL_MODE)
+    return deny(
+      "mode_mismatch",
+      "This unpublished legacy mode requires the proposal lifecycle; do not dispatch the mutation directly.",
+      "blocked"
+    );
   if (!["self_serve", "conditional_self_serve", "seller_managed", "requires_approval"].includes(entry.mode))
     return deny("condition_unresolved", "Unknown live action mode; refresh the seller declaration.", "unknown");
   if (term && (entry.mode !== term.service_mode || !slaWithin(term.processing_sla, entry.sla)))

package/dist/lib/media-buy/available-actions.d.mts

@@ -17,6 +17,13 @@ export interface AvailableActionsResult {
      */
     deprecationHint?: string;
 }
+/** Unpublished pre-GA mode retained only to route persisted data to recovery. */
+export declare const LEGACY_REQUIRES_PROPOSAL_MODE: "requires_proposal";
+export type LegacyRequiresProposalAction = Omit<MediaBuyAvailableAction, 'mode'> & {
+    mode: typeof LEGACY_REQUIRES_PROPOSAL_MODE;
+};
+export type RuntimeCompatibleAvailableAction = MediaBuyAvailableAction | LegacyRequiresProposalAction;
+export declare function isLegacyRequiresProposalAction(entry: RuntimeCompatibleAvailableAction): entry is LegacyRequiresProposalAction;
 /**
  * Hook for tests (this repo's and downstream adopters') to reset the
  * one-shot warning gate. Underscore-prefixed name signals it's not part
@@ -49,7 +56,7 @@ export declare function getAvailableActions(buy: MediaBuyActionContext, options?
 export declare function findAvailableAction(buy: MediaBuyActionContext, action: MediaBuyActionId, options?: {
     silent?: boolean;
 }): {
-    entry: MediaBuyAvailableAction;
+    entry: RuntimeCompatibleAvailableAction;
     result: AvailableActionsResult;
 } | undefined;
 /**

package/dist/lib/media-buy/available-actions.d.ts

@@ -17,6 +17,13 @@ export interface AvailableActionsResult {
      */
     deprecationHint?: string;
 }
+/** Unpublished pre-GA mode retained only to route persisted data to recovery. */
+export declare const LEGACY_REQUIRES_PROPOSAL_MODE: "requires_proposal";
+export type LegacyRequiresProposalAction = Omit<MediaBuyAvailableAction, 'mode'> & {
+    mode: typeof LEGACY_REQUIRES_PROPOSAL_MODE;
+};
+export type RuntimeCompatibleAvailableAction = MediaBuyAvailableAction | LegacyRequiresProposalAction;
+export declare function isLegacyRequiresProposalAction(entry: RuntimeCompatibleAvailableAction): entry is LegacyRequiresProposalAction;
 /**
  * Hook for tests (this repo's and downstream adopters') to reset the
  * one-shot warning gate. Underscore-prefixed name signals it's not part
@@ -49,7 +56,7 @@ export declare function getAvailableActions(buy: MediaBuyActionContext, options?
 export declare function findAvailableAction(buy: MediaBuyActionContext, action: MediaBuyActionId, options?: {
     silent?: boolean;
 }): {
-    entry: MediaBuyAvailableAction;
+    entry: RuntimeCompatibleAvailableAction;
     result: AvailableActionsResult;
 } | undefined;
 /**

package/dist/lib/media-buy/available-actions.js

@@ -18,12 +18,25 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var available_actions_exports = {};
 __export(available_actions_exports, {
+  LEGACY_REQUIRES_PROPOSAL_MODE: () => LEGACY_REQUIRES_PROPOSAL_MODE,
   __resetValidActionsWarningForTests: () => __resetValidActionsWarningForTests,
   findAvailableAction: () => findAvailableAction,
   getAvailableActions: () => getAvailableActions,
-  getRollupParent: () => getRollupParent
+  getRollupParent: () => getRollupParent,
+  isLegacyRequiresProposalAction: () => isLegacyRequiresProposalAction
 });
 module.exports = __toCommonJS(available_actions_exports);
+const LEGACY_REQUIRES_PROPOSAL_MODE = "requires_proposal";
+const RUNTIME_RECOGNIZED_MODES = /* @__PURE__ */ new Set([
+  "self_serve",
+  "conditional_self_serve",
+  "seller_managed",
+  "requires_approval",
+  LEGACY_REQUIRES_PROPOSAL_MODE
+]);
+function isLegacyRequiresProposalAction(entry) {
+  return entry.mode === LEGACY_REQUIRES_PROPOSAL_MODE;
+}
 const DEPRECATION_HINT = "seller emitted `valid_actions[]` only (legacy 3.0). mode and sla unknown; preflight assumes self_serve. sellers SHOULD populate `available_actions[]` during 3.x.";
 let warnedOnce = false;
 function emitDeprecationWarning() {
@@ -54,7 +67,7 @@ function getAvailableActions(buy, options = {}) {
 function findAvailableAction(buy, action, options = {}) {
   const result = getAvailableActions(buy, options);
   const direct = result.actions.find((a) => a.action === action);
-  const knownMode = (entry) => ["self_serve", "conditional_self_serve", "seller_managed", "requires_approval"].includes(entry.mode);
+  const knownMode = (entry) => RUNTIME_RECOGNIZED_MODES.has(entry.mode);
   if (direct) return knownMode(direct) ? { entry: direct, result } : void 0;
   const rollupParent = ROLLUP_PARENT_OF[action];
   if (rollupParent) {
@@ -83,8 +96,10 @@ function getRollupParent(action) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  LEGACY_REQUIRES_PROPOSAL_MODE,
   __resetValidActionsWarningForTests,
   findAvailableAction,
   getAvailableActions,
-  getRollupParent
+  getRollupParent,
+  isLegacyRequiresProposalAction
 });

package/dist/lib/media-buy/available-actions.mjs

@@ -1,3 +1,14 @@
+const LEGACY_REQUIRES_PROPOSAL_MODE = "requires_proposal";
+const RUNTIME_RECOGNIZED_MODES = /* @__PURE__ */ new Set([
+  "self_serve",
+  "conditional_self_serve",
+  "seller_managed",
+  "requires_approval",
+  LEGACY_REQUIRES_PROPOSAL_MODE
+]);
+function isLegacyRequiresProposalAction(entry) {
+  return entry.mode === LEGACY_REQUIRES_PROPOSAL_MODE;
+}
 const DEPRECATION_HINT = "seller emitted `valid_actions[]` only (legacy 3.0). mode and sla unknown; preflight assumes self_serve. sellers SHOULD populate `available_actions[]` during 3.x.";
 let warnedOnce = false;
 function emitDeprecationWarning() {
@@ -28,7 +39,7 @@ function getAvailableActions(buy, options = {}) {
 function findAvailableAction(buy, action, options = {}) {
   const result = getAvailableActions(buy, options);
   const direct = result.actions.find((a) => a.action === action);
-  const knownMode = (entry) => ["self_serve", "conditional_self_serve", "seller_managed", "requires_approval"].includes(entry.mode);
+  const knownMode = (entry) => RUNTIME_RECOGNIZED_MODES.has(entry.mode);
   if (direct) return knownMode(direct) ? { entry: direct, result } : void 0;
   const rollupParent = ROLLUP_PARENT_OF[action];
   if (rollupParent) {
@@ -56,8 +67,10 @@ function getRollupParent(action) {
   return ROLLUP_PARENT_OF[action];
 }
 export {
+  LEGACY_REQUIRES_PROPOSAL_MODE,
   __resetValidActionsWarningForTests,
   findAvailableAction,
   getAvailableActions,
-  getRollupParent
+  getRollupParent,
+  isLegacyRequiresProposalAction
 };

package/dist/lib/media-buy/index.d.mts

@@ -13,6 +13,7 @@ export type { MediaBuyUpdateFieldAction, StructuredOnlyMediaBuyAction, UpdateFie
 export { ACTIONS_BY_FIELD, STRUCTURED_ONLY_MEDIA_BUY_ACTIONS, UPDATE_FIELDS_BY_ACTION, } from './update-fields.generated.mjs';
 export { applyTargetingInput, hasTargetingClears, resolveTargetingInput } from './targeting-input.mjs';
 export type { ResolvedTargetingInput, TargetingInputFor } from './targeting-input.mjs';
+export type { CreateTargetingInput, UpdateTargetingInput } from '../types/index.mjs';
 export * from './compatibility.mjs';
 export * from './established-proposal-store.mjs';
 export * from './legacy-purchase-continuation.mjs';

package/dist/lib/media-buy/index.d.ts

@@ -13,6 +13,7 @@ export type { MediaBuyUpdateFieldAction, StructuredOnlyMediaBuyAction, UpdateFie
 export { ACTIONS_BY_FIELD, STRUCTURED_ONLY_MEDIA_BUY_ACTIONS, UPDATE_FIELDS_BY_ACTION, } from './update-fields.generated';
 export { applyTargetingInput, hasTargetingClears, resolveTargetingInput } from './targeting-input';
 export type { ResolvedTargetingInput, TargetingInputFor } from './targeting-input';
+export type { CreateTargetingInput, UpdateTargetingInput } from '../types';
 export * from './compatibility';
 export * from './established-proposal-store';
 export * from './legacy-purchase-continuation';

package/dist/lib/media-buy/preflight.js

@@ -59,7 +59,8 @@ function tasksForLegacyMutation(action) {
   );
 }
 function isAvailable(buy, action) {
-  return (0, import_available_actions.findAvailableAction)(buy, action, { silent: true }) !== void 0;
+  const match = (0, import_available_actions.findAvailableAction)(buy, action, { silent: true });
+  return match !== void 0 && !(0, import_available_actions.isLegacyRequiresProposalAction)(match.entry);
 }
 const canPause = (buy) => isAvailable(buy, "pause");
 const canResume = (buy) => isAvailable(buy, "resume");
@@ -123,6 +124,16 @@ function preflightUpdateMediaBuy(currentBuy, request, options = {}) {
         }
       }
     }
+    const lookup = (0, import_available_actions.findAvailableAction)(currentBuy, resolvedAction.action, { silent: true });
+    if (lookup && (0, import_available_actions.isLegacyRequiresProposalAction)(lookup.entry)) {
+      denials.push({
+        action: resolvedAction.action,
+        reason: "mode_mismatch",
+        recovery: recoveryForModeMismatch(resolvedAction.action, result.actions)
+      });
+      continue;
+    }
+    const liveEntry = lookup?.entry;
     if (strict || options.proposal !== void 0 || resolvedAction.action === "update_name") {
       const assessment = (0, import_action_assessment.assessActionAvailability)(assessmentBuy, resolvedAction.action, { ...options, request });
       if (assessment.status === "currently_unavailable") {
@@ -130,12 +141,11 @@ function preflightUpdateMediaBuy(currentBuy, request, options = {}) {
         continue;
       }
     }
-    const lookup = (0, import_available_actions.findAvailableAction)(currentBuy, resolvedAction.action, { silent: true });
-    if (!lookup) {
+    if (!liveEntry) {
       denials.push({ action: resolvedAction.action, reason: "not_supported_on_buy" });
       continue;
     }
-    if (options.adcpVersion && !(0, import_action_contracts.liveActionFitsVersion)(lookup.entry, options.adcpVersion)) {
+    if (options.adcpVersion && !(0, import_action_contracts.liveActionFitsVersion)(liveEntry, options.adcpVersion)) {
       denials.push({
         action: resolvedAction.action,
         reason: "condition_unresolved",
@@ -149,14 +159,14 @@ function preflightUpdateMediaBuy(currentBuy, request, options = {}) {
       });
       continue;
     }
-    if (!strict && lookup.entry.task !== void 0 && !tasksForLegacyMutation(resolvedAction.action).includes(lookup.entry.task)) {
+    if (!strict && liveEntry.task !== void 0 && !tasksForLegacyMutation(resolvedAction.action).includes(liveEntry.task)) {
       denials.push({ action: resolvedAction.action, reason: "mode_mismatch" });
       continue;
     }
-    if (!strict && lookup.entry.applicable_package_ids !== void 0) {
+    if (!strict && liveEntry.applicable_package_ids !== void 0) {
       const scoped = decomposition.mutations.filter((m) => m.action === resolvedAction.action);
-      const ids = lookup.entry.applicable_package_ids;
-      if ((0, import_action_contracts.liveActionIssues)([lookup.entry]).length || !scoped.length) {
+      const ids = liveEntry.applicable_package_ids;
+      if ((0, import_action_contracts.liveActionIssues)([liveEntry]).length || !scoped.length) {
         denials.push({ action: resolvedAction.action, reason: "condition_unresolved" });
         continue;
       }
@@ -165,12 +175,12 @@ function preflightUpdateMediaBuy(currentBuy, request, options = {}) {
         continue;
       }
     }
-    if (!strict && options.task !== "update_media_buy" && options.task !== (lookup.entry.task ?? "update_media_buy")) {
+    if (!strict && options.task !== "update_media_buy" && options.task !== (liveEntry.task ?? "update_media_buy")) {
       denials.push({ action: resolvedAction.action, reason: "mode_mismatch" });
       continue;
     }
-    matched.push(lookup.entry);
-    modes.push(lookup.entry.mode);
+    matched.push(liveEntry);
+    modes.push(liveEntry.mode);
   }
   if (strict && options.task !== "update_media_buy" && denials.length === 0 && new Set(matched.map((entry) => entry.task ?? "update_media_buy")).size > 1) {
     for (const action of resolved) denials.push({ action: action.action, reason: "mode_mismatch" });
@@ -195,7 +205,8 @@ function preflightUpdateMediaBuy(currentBuy, request, options = {}) {
   };
 }
 function recoveryForModeMismatch(attemptedAction, currentlyAvailable) {
-  const entry = currentlyAvailable.find((a) => a.action === attemptedAction);
+  const rollup = (0, import_available_actions.getRollupParent)(attemptedAction);
+  const entry = currentlyAvailable.find((a) => a.action === attemptedAction) ?? (rollup === void 0 ? void 0 : currentlyAvailable.find((a) => a.action === rollup));
   if (!entry) return void 0;
   switch (entry.mode) {
     case "seller_managed":