@adcp/sdk 14.0.0-rc.38 → 14.0.0-rc.39

package/dist/lib/server/media-buy-action-resolver.d.mts

@@ -0,0 +1,63 @@
+import type { ActionBuy, ActionProduct, LiveMediaBuyAction, MediaBuyTask, ProposalChangeTerm } from '../media-buy/action-types.mjs';
+import { type ActionAvailability } from '../media-buy/action-assessment.mjs';
+import type { SLAWindow, UpdateMediaBuyRequestLike } from '../media-buy/types.mjs';
+export interface SellerActionDecision {
+    /** These are seller-owned, evaluated gates, never copied from buyer request data. Unknown is a denial. */
+    authorization: boolean | 'unknown';
+    governance: boolean | 'unknown';
+    policy: boolean | 'unknown';
+    /** Explicit seller evaluation of all opaque identifiers, scoped to this term/current request. */
+    conditionsSatisfied?: boolean;
+    /** A selected task must be one of the canonical action's permitted tasks. */
+    task?: MediaBuyTask;
+    /** Optional tighter elapsed maxima; cannot discard a committed maximum. */
+    sla?: SLAWindow;
+    /** rc.3 package scope is an explicit seller narrowing, never inferred from a buyer request. */
+    applicable_package_ids?: readonly string[];
+}
+export interface SellerActionResolutionOptions {
+    /** Trusted current snapshot from the seller store after account and revision checks. */
+    buy: ActionBuy;
+    /** Every affected product, including those on sibling packages for aggregate changes. Never union rights. */
+    productPolicy?: readonly ActionProduct[];
+    decide: (term: Readonly<ProposalChangeTerm>) => SellerActionDecision;
+    /** Current output is 3.2. A deliberate 3.1 projection emits opaque terms_ref and requires_approval. */
+    wireVersion?: '3.2' | '3.1';
+    /** Exact served schema version; defaults to the SDK pin. rc.3 features require rc.3 or newer. */
+    adcpVersion?: string;
+    /** Emit a deliberate equal compatibility alias alongside the 3.2 identity. */
+    emitTermsRefAlias?: boolean;
+    /** Separately assess this request without replacing the full live projection. */
+    request?: UpdateMediaBuyRequestLike;
+    /** Noncommercial metadata authority is explicit, never fabricated as a proposal term. */
+    metadata?: {
+        update_name?: SellerActionDecision;
+    };
+    now?: number;
+}
+export interface SellerActionResolution {
+    available_actions: LiveMediaBuyAction[];
+    unavailable: ActionAvailability[];
+    /** One assessment per decomposed requested action, including gate denials and missing rights. */
+    request_assessments?: ActionAvailability[];
+}
+/**
+ * One builder for product acceptance and live projection, alongside validActionsForStatus.
+ * It does not authenticate tokens, load state, persist terms, or mutate a buy.
+ * Call under the existing authorization, governance, revision and idempotency
+ * boundary. Gates and conditions are seller-owned results, not buyer assertions.
+ */
+export declare const mediaBuyActionResolver: {
+    /**
+     * Explicitly accept complete binding terms selected by the seller from all
+     * affected product templates. Nothing is materialized from a product alone.
+     * Omitting sellerAccepted or supplying false throws, including for JS callers.
+     */
+    materialize(input: {
+        products: readonly ActionProduct[];
+        acceptedTerms: readonly ProposalChangeTerm[];
+        sellerAccepted: true;
+        currency?: string;
+    }): ProposalChangeTerm[];
+    resolve(input: SellerActionResolutionOptions): SellerActionResolution;
+};

package/dist/lib/server/media-buy-action-resolver.d.ts

@@ -0,0 +1,63 @@
+import type { ActionBuy, ActionProduct, LiveMediaBuyAction, MediaBuyTask, ProposalChangeTerm } from '../media-buy/action-types';
+import { type ActionAvailability } from '../media-buy/action-assessment';
+import type { SLAWindow, UpdateMediaBuyRequestLike } from '../media-buy/types';
+export interface SellerActionDecision {
+    /** These are seller-owned, evaluated gates, never copied from buyer request data. Unknown is a denial. */
+    authorization: boolean | 'unknown';
+    governance: boolean | 'unknown';
+    policy: boolean | 'unknown';
+    /** Explicit seller evaluation of all opaque identifiers, scoped to this term/current request. */
+    conditionsSatisfied?: boolean;
+    /** A selected task must be one of the canonical action's permitted tasks. */
+    task?: MediaBuyTask;
+    /** Optional tighter elapsed maxima; cannot discard a committed maximum. */
+    sla?: SLAWindow;
+    /** rc.3 package scope is an explicit seller narrowing, never inferred from a buyer request. */
+    applicable_package_ids?: readonly string[];
+}
+export interface SellerActionResolutionOptions {
+    /** Trusted current snapshot from the seller store after account and revision checks. */
+    buy: ActionBuy;
+    /** Every affected product, including those on sibling packages for aggregate changes. Never union rights. */
+    productPolicy?: readonly ActionProduct[];
+    decide: (term: Readonly<ProposalChangeTerm>) => SellerActionDecision;
+    /** Current output is 3.2. A deliberate 3.1 projection emits opaque terms_ref and requires_approval. */
+    wireVersion?: '3.2' | '3.1';
+    /** Exact served schema version; defaults to the SDK pin. rc.3 features require rc.3 or newer. */
+    adcpVersion?: string;
+    /** Emit a deliberate equal compatibility alias alongside the 3.2 identity. */
+    emitTermsRefAlias?: boolean;
+    /** Separately assess this request without replacing the full live projection. */
+    request?: UpdateMediaBuyRequestLike;
+    /** Noncommercial metadata authority is explicit, never fabricated as a proposal term. */
+    metadata?: {
+        update_name?: SellerActionDecision;
+    };
+    now?: number;
+}
+export interface SellerActionResolution {
+    available_actions: LiveMediaBuyAction[];
+    unavailable: ActionAvailability[];
+    /** One assessment per decomposed requested action, including gate denials and missing rights. */
+    request_assessments?: ActionAvailability[];
+}
+/**
+ * One builder for product acceptance and live projection, alongside validActionsForStatus.
+ * It does not authenticate tokens, load state, persist terms, or mutate a buy.
+ * Call under the existing authorization, governance, revision and idempotency
+ * boundary. Gates and conditions are seller-owned results, not buyer assertions.
+ */
+export declare const mediaBuyActionResolver: {
+    /**
+     * Explicitly accept complete binding terms selected by the seller from all
+     * affected product templates. Nothing is materialized from a product alone.
+     * Omitting sellerAccepted or supplying false throws, including for JS callers.
+     */
+    materialize(input: {
+        products: readonly ActionProduct[];
+        acceptedTerms: readonly ProposalChangeTerm[];
+        sellerAccepted: true;
+        currency?: string;
+    }): ProposalChangeTerm[];
+    resolve(input: SellerActionResolutionOptions): SellerActionResolution;
+};

package/dist/lib/server/media-buy-action-resolver.js

@@ -0,0 +1,297 @@
+"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 media_buy_action_resolver_exports = {};
+__export(media_buy_action_resolver_exports, {
+  mediaBuyActionResolver: () => mediaBuyActionResolver
+});
+module.exports = __toCommonJS(media_buy_action_resolver_exports);
+var import_version = require('../version.js');
+var import_action_contracts = require('../media-buy/action-contracts.js');
+var import_action_assessment = require('../media-buy/action-assessment.js');
+var import_mutations = require('../media-buy/mutations.js');
+const mediaBuyActionResolver = {
+  /**
+   * Explicitly accept complete binding terms selected by the seller from all
+   * affected product templates. Nothing is materialized from a product alone.
+   * Omitting sellerAccepted or supplying false throws, including for JS callers.
+   */
+  materialize(input) {
+    if (input.sellerAccepted !== true)
+      throw new TypeError("Explicit seller acceptance is required to materialize binding change terms.");
+    const issues = (0, import_action_contracts.changeTermIssues)(input.acceptedTerms, input.currency);
+    for (const product of input.products)
+      issues.push(...(0, import_action_contracts.productTemplateIssues)(product.allowed_actions ?? [], input.currency));
+    if (!input.products.length) issues.push("Every affected product must be supplied.");
+    if (issues.length) throw new TypeError(issues.join("; "));
+    const materialized = structuredClone([...input.acceptedTerms]);
+    for (const term of materialized) {
+      const templates = input.products.map((product) => (0, import_action_contracts.findProductAction)(product.allowed_actions, term.action));
+      const constraints = templates.find((t) => t?.constraints)?.constraints;
+      const sla = templates.find((t) => t?.sla)?.sla;
+      if (term.constraints === void 0 && constraints !== void 0) term.constraints = structuredClone(constraints);
+      if (term.processing_sla === void 0 && sla !== void 0) term.processing_sla = structuredClone(sla);
+      if (!term.allowed_statuses && templates.some((t) => t?.allowed_statuses)) {
+        term.allowed_statuses = (0, import_action_contracts.actionAllowedStatuses)(term).filter(
+          (status) => templates.every((t) => !t?.allowed_statuses || t.allowed_statuses.includes(status))
+        );
+      }
+      const reference = templates[0]?.terms_ref;
+      if (reference && templates.every((t) => t?.terms_ref === reference)) term.terms_ref ??= reference;
+      for (const product of input.products) {
+        const template = (0, import_action_contracts.findProductAction)(product.allowed_actions, term.action);
+        if (!template || !template.modes.includes(term.service_mode) || !(0, import_action_contracts.slaWithin)(template.sla, term.processing_sla)) {
+          issues.push("Accepted terms exceed product template.");
+          continue;
+        }
+        if (template.allowed_statuses && (0, import_action_contracts.actionAllowedStatuses)(term).some((s) => !template.allowed_statuses.includes(s)))
+          issues.push("Accepted status scope exceeds product template.");
+        if (template.constraints && !constraintsWithin(template.constraints, term.constraints))
+          issues.push("Materialized constraints must retain the product bound.");
+      }
+    }
+    issues.push(...(0, import_action_contracts.changeTermIssues)(materialized, input.currency));
+    if (issues.length) throw new TypeError(issues.join("; "));
+    return materialized;
+  },
+  resolve(input) {
+    const terms = input.buy.accepted_proposal?.commercial_terms?.change_terms ?? [];
+    const currency = typeof input.buy.total_budget === "object" ? input.buy.total_budget?.currency : input.buy.currency;
+    const issues = (0, import_action_contracts.changeTermIssues)(terms, currency);
+    for (const product of input.productPolicy ?? [])
+      issues.push(...(0, import_action_contracts.productTemplateIssues)(product.allowed_actions ?? [], currency));
+    if (issues.length) throw new TypeError(issues.join("; "));
+    const available_actions = [], unavailable = [], request_assessments = [];
+    const requestedActions = input.request ? (0, import_mutations.decomposeUpdateMediaBuy)(input.buy, input.request).actions : [];
+    for (const original of terms) {
+      const term = structuredClone(original);
+      const decision = input.decide(structuredClone(term));
+      const blocked = (message, unknown = false) => unavailable.push({
+        status: "currently_unavailable",
+        action: term.action,
+        reason: "condition_unresolved",
+        certainty: unknown ? "unknown" : "blocked",
+        message
+      });
+      if (decision.authorization !== true || decision.governance !== true || decision.policy !== true) {
+        blocked(
+          "Seller authorization, governance, and policy must all admit the action.",
+          [decision.authorization, decision.governance, decision.policy].includes("unknown")
+        );
+        continue;
+      }
+      if (term.conditions?.length && decision.conditionsSatisfied !== true) {
+        blocked("Seller conditions are unresolved.", true);
+        continue;
+      }
+      let productBlocked = false;
+      for (const product of input.productPolicy ?? []) {
+        const template = (0, import_action_contracts.findProductAction)(product.allowed_actions, term.action);
+        if (!template || !template.modes.includes(term.service_mode) || !(0, import_action_contracts.slaWithin)(template.sla, decision.sla ?? term.processing_sla) || template.allowed_statuses && !template.allowed_statuses.includes(input.buy.status)) {
+          productBlocked = true;
+          break;
+        }
+        if (template.constraints && !constraintsWithin(template.constraints, term.constraints)) productBlocked = true;
+      }
+      if (productBlocked) {
+        unavailable.push({
+          status: "currently_unavailable",
+          action: term.action,
+          reason: "not_supported_on_product",
+          certainty: "blocked",
+          message: "Not every affected product currently admits this accepted action."
+        });
+        continue;
+      }
+      if (input.wireVersion !== "3.1" && !(0, import_action_contracts.supportsChangeTermIdentity)(input.adcpVersion ?? import_version.ADCP_VERSION)) {
+        blocked("Accepted change-term links require a beta.9-or-newer served schema.", true);
+        continue;
+      }
+      if (!(0, import_action_contracts.supportsRc3Actions)(input.adcpVersion ?? import_version.ADCP_VERSION) && (term.action === "update_media_buy_frequency_cap" || decision.applicable_package_ids !== void 0)) {
+        blocked("This action or package scope requires an rc.3-or-newer served schema.", true);
+        continue;
+      }
+      const entry = {
+        action: term.action,
+        mode: term.service_mode,
+        task: decision.task ?? (0, import_action_contracts.defaultMediaBuyActionTask)(term.action),
+        change_term_id: term.term_id,
+        ...decision.applicable_package_ids && { applicable_package_ids: [...decision.applicable_package_ids] },
+        ...term.processing_sla && { sla: structuredClone(term.processing_sla) },
+        ...decision.sla && { sla: structuredClone(decision.sla) }
+      };
+      if (decision.applicable_package_ids !== void 0 && (!decision.applicable_package_ids.length || new Set(decision.applicable_package_ids).size !== decision.applicable_package_ids.length || decision.applicable_package_ids.some(
+        (id) => typeof id !== "string" || !id || !input.buy.packages?.some((p) => p.package_id === id)
+      ))) {
+        blocked("Invalid or unknown package scope.", true);
+        continue;
+      }
+      if (["pause", "resume"].includes(term.action) && entry.applicable_package_ids) {
+        const eligible = entry.applicable_package_ids.filter((id) => {
+          const status = (0, import_action_contracts.packageActionStatus)(input.buy.packages?.find((p) => p.package_id === id));
+          return status !== void 0 && (0, import_action_contracts.actionAllowedStatuses)({ action: term.action }).includes(
+            status
+          );
+        });
+        if (eligible.length) entry.applicable_package_ids = eligible;
+      }
+      if (input.wireVersion === "3.1" && (!(0, import_action_contracts.legacyActionSupported)(term.action) || decision.applicable_package_ids !== void 0)) {
+        blocked("This right cannot be represented safely in the requested legacy projection.", true);
+        continue;
+      }
+      const evaluatedTerm = { ...term };
+      delete evaluatedTerm.conditions;
+      const evaluatedBuy = {
+        ...input.buy,
+        accepted_proposal: { ...input.buy.accepted_proposal, commercial_terms: { change_terms: [evaluatedTerm] } },
+        available_actions: [entry]
+      };
+      if (input.request && requestedActions.some((a) => a.action === term.action))
+        request_assessments.push(
+          structuredClone(
+            (0, import_action_assessment.assessActionAvailability)(evaluatedBuy, term.action, { request: input.request, now: input.now })
+          )
+        );
+      const constraint = evaluatedTerm.constraints;
+      const hasTimingGate = constraint?.kind === "effective_timing" && (constraint.earliest_effective_at !== void 0 || constraint.latest_effective_at !== void 0);
+      if (!hasTimingGate) delete evaluatedTerm.constraints;
+      else
+        evaluatedTerm.constraints = {
+          kind: "effective_timing",
+          ...constraint.earliest_effective_at !== void 0 && {
+            earliest_effective_at: constraint.earliest_effective_at
+          },
+          ...constraint.latest_effective_at !== void 0 && { latest_effective_at: constraint.latest_effective_at }
+        };
+      const packageLifecycleRequest = ["pause", "resume"].includes(term.action) && entry.applicable_package_ids ? {
+        packages: entry.applicable_package_ids.map((package_id) => ({
+          package_id,
+          paused: term.action === "pause"
+        }))
+      } : void 0;
+      evaluatedBuy.available_actions = [
+        { ...entry, ...packageLifecycleRequest ? {} : { applicable_package_ids: void 0 } }
+      ];
+      const result = (0, import_action_assessment.assessActionAvailability)(evaluatedBuy, term.action, {
+        request: packageLifecycleRequest ?? (hasTimingGate ? {} : void 0),
+        now: input.now
+      });
+      if (result.status !== "available_now") {
+        unavailable.push(result);
+        continue;
+      }
+      if (input.wireVersion === "3.1") {
+        const legacy = {
+          ...entry,
+          terms_ref: term.term_id,
+          mode: term.service_mode === "seller_managed" ? "requires_approval" : term.service_mode
+        };
+        delete legacy.change_term_id;
+        delete legacy.task;
+        available_actions.push(legacy);
+      } else available_actions.push({ ...entry, ...input.emitTermsRefAlias && { terms_ref: term.term_id } });
+    }
+    const metadata = input.metadata?.update_name;
+    if (metadata) {
+      const entry = {
+        action: "update_name",
+        mode: "self_serve",
+        task: metadata.task ?? "control_media_buy",
+        ...metadata.sla && { sla: structuredClone(metadata.sla) }
+      };
+      const result = (0, import_action_assessment.assessActionAvailability)({ ...input.buy, available_actions: [entry] }, "update_name", {
+        adcpVersion: input.adcpVersion ?? import_version.ADCP_VERSION
+      });
+      if (metadata.authorization === true && metadata.governance === true && metadata.policy === true && metadata.applicable_package_ids === void 0 && (input.productPolicy ?? []).every((p) => {
+        const template = (0, import_action_contracts.findProductAction)(p.allowed_actions, "update_name");
+        return template?.modes.includes("self_serve") && (!template.allowed_statuses || template.allowed_statuses.includes(input.buy.status)) && (0, import_action_contracts.slaWithin)(template.sla, entry.sla);
+      }) && result.status === "available_now") {
+        if (input.wireVersion !== "3.1") available_actions.push(entry);
+        else
+          unavailable.push({
+            status: "currently_unavailable",
+            action: "update_name",
+            reason: "not_supported_on_buy",
+            certainty: "blocked",
+            message: "Naming is not in the 3.1.19 action vocabulary."
+          });
+      } else
+        unavailable.push(
+          result.status === "currently_unavailable" ? result : {
+            status: "currently_unavailable",
+            action: "update_name",
+            reason: "condition_unresolved",
+            certainty: "unknown",
+            message: "Explicit seller metadata gates must all admit this action."
+          }
+        );
+    }
+    return {
+      available_actions,
+      unavailable,
+      ...input.request && {
+        request_assessments: requestedActions.map(
+          ({ action }) => structuredClone(
+            request_assessments.find((assessment) => assessment.action === action) ?? unavailable.find((assessment) => assessment.action === action) ?? (0, import_action_assessment.assessActionAvailability)({ ...input.buy, available_actions }, action, {
+              request: input.request,
+              now: input.now,
+              adcpVersion: input.adcpVersion ?? import_version.ADCP_VERSION
+            })
+          )
+        )
+      }
+    };
+  }
+};
+function sameData(a, b) {
+  if (a === b) return true;
+  if (!a || !b || typeof a !== "object" || typeof b !== "object" || Array.isArray(a) !== Array.isArray(b)) return false;
+  const left = Object.keys(a), right = Object.keys(b);
+  return left.length === right.length && left.every(
+    (k) => Object.hasOwn(b, k) && sameData(a[k], b[k])
+  );
+}
+function constraintsWithin(ceiling, candidate) {
+  if (sameData(ceiling, candidate)) return true;
+  if (!ceiling || !candidate || typeof ceiling !== "object" || typeof candidate !== "object") return false;
+  const a = ceiling, b = candidate;
+  if (a.kind !== b.kind) return false;
+  return Object.keys(a).filter((key) => key !== "kind").every((key) => {
+    if (sameData(a[key], b[key])) return true;
+    if (b[key] === void 0) return false;
+    const minimum = key.startsWith("min_") || key === "minimum_notice" || key.startsWith("earliest_");
+    let left = a[key], right = b[key];
+    if (key.endsWith("_amount")) {
+      const x = left, y = right;
+      if (x.currency !== y.currency) return false;
+      left = x.amount;
+      right = y.amount;
+    } else if (key === "max_change" || key === "minimum_notice") {
+      left = (0, import_action_contracts.elapsedDuration)(left);
+      right = (0, import_action_contracts.elapsedDuration)(right);
+    } else if (key.startsWith("earliest_") || key.startsWith("latest_")) {
+      left = Date.parse(String(left));
+      right = Date.parse(String(right));
+    }
+    return typeof left === "number" && Number.isFinite(left) && typeof right === "number" && Number.isFinite(right) && (minimum ? right >= left : right <= left);
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  mediaBuyActionResolver
+});