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

package/dist/lib/media-buy/action-constraints.d.mts

@@ -0,0 +1,9 @@
+import type { ActionBuy, ConstraintAssessment, ProposalChangeTerm } from './action-types.mjs';
+import type { DecomposedUpdateMediaBuyMutation } from './mutations.mjs';
+import type { UpdateMediaBuyRequestLike } from './types.mjs';
+export interface ConstraintEvaluationOptions {
+    /** Captured request time in epoch milliseconds. Required for wall-clock bounds; never inferred from prose. */
+    now?: number;
+}
+/** Evaluate only portable data. Seller conditions and calendar/campaign durations stay unknown. */
+export declare function evaluateChangeTermConstraints(term: ProposalChangeTerm, buy: ActionBuy, request: UpdateMediaBuyRequestLike, mutations: readonly DecomposedUpdateMediaBuyMutation[], options?: ConstraintEvaluationOptions): ConstraintAssessment;

package/dist/lib/media-buy/action-constraints.d.ts

@@ -0,0 +1,9 @@
+import type { ActionBuy, ConstraintAssessment, ProposalChangeTerm } from './action-types';
+import type { DecomposedUpdateMediaBuyMutation } from './mutations';
+import type { UpdateMediaBuyRequestLike } from './types';
+export interface ConstraintEvaluationOptions {
+    /** Captured request time in epoch milliseconds. Required for wall-clock bounds; never inferred from prose. */
+    now?: number;
+}
+/** Evaluate only portable data. Seller conditions and calendar/campaign durations stay unknown. */
+export declare function evaluateChangeTermConstraints(term: ProposalChangeTerm, buy: ActionBuy, request: UpdateMediaBuyRequestLike, mutations: readonly DecomposedUpdateMediaBuyMutation[], options?: ConstraintEvaluationOptions): ConstraintAssessment;

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

@@ -0,0 +1,170 @@
+"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 action_constraints_exports = {};
+__export(action_constraints_exports, {
+  evaluateChangeTermConstraints: () => evaluateChangeTermConstraints
+});
+module.exports = __toCommonJS(action_constraints_exports);
+var import_action_contracts = require('./action-contracts.js');
+const finite = (value) => typeof value === "number" && Number.isFinite(value);
+const timestamp = (value) => {
+  const raw = typeof value === "object" && value !== null && "datetime" in value ? value.datetime : value;
+  if (typeof raw !== "string") return void 0;
+  const parsed = Date.parse(raw);
+  return Number.isFinite(parsed) ? parsed : void 0;
+};
+const unknown = (constraint, path) => ({
+  status: "unknown",
+  constraint,
+  path,
+  message: `Cannot evaluate ${constraint} at ${path}; supply the committed baseline, currency, and captured request time required by that bound.`
+});
+const exceeded = (constraint, path) => ({
+  status: "exceeded",
+  constraint,
+  path,
+  message: "The requested change exceeds the accepted bound; refine the accepted proposal."
+});
+function evaluateChangeTermConstraints(term, buy, request, mutations, options = {}) {
+  if (request.total_budget && mutations.some((m) => m.action === term.action && ["total_budget.amount", "budget_allocation"].includes(m.field))) {
+    const currency = typeof buy.total_budget === "object" ? buy.total_budget?.currency : buy.currency;
+    if (currency === void 0) return unknown("currency", "total_budget.currency");
+    if (request.total_budget.currency !== currency) return exceeded("currency_mismatch", "total_budget.currency");
+  }
+  if (term.constraints === void 0) return { status: "satisfied" };
+  if ((0, import_action_contracts.changeConstraintIssues)(term.action, term.constraints).length) return unknown("invalid_constraints", term.action);
+  const c = term.constraints;
+  const relevant = mutations.filter((m) => m.action === term.action);
+  let unresolved;
+  const recordUnknown = (key, path) => {
+    unresolved ??= unknown(key, path);
+  };
+  if (c.kind === "budget") {
+    if (request.new_packages?.length && (c.min_result_amount || c.max_result_amount))
+      return unknown("added_package_budget", "new_packages");
+    const values = relevant.filter((m) => /(?:budget(?:\.amount)?|daily_budget_cap|min_spend_target)$/.test(m.field));
+    if (!values.length && term.action === "update_budget_allocation" && relevant.some((m) => m.field === "budget_allocation")) {
+      const amount = typeof buy.total_budget === "object" ? buy.total_budget?.amount : buy.total_budget;
+      values.push({
+        action: term.action,
+        field: "budget_allocation",
+        path: "budget_allocation",
+        scope: "buy",
+        from: amount,
+        to: request.total_budget?.amount ?? amount
+      });
+    }
+    if (!values.length) return unknown("cannot_preflight", term.action);
+    const currency = typeof buy.total_budget === "object" ? buy.total_budget?.currency : buy.currency;
+    for (const m of values) {
+      if (m.to === null && (m.field === "packages[].budget" || m.field.endsWith("daily_budget_cap")) && term.action === "increase_budget") {
+        if (c.max_delta_amount || c.max_delta_percent !== void 0 || c.max_result_amount)
+          return exceeded("unbounded_result", m.path);
+        continue;
+      }
+      if (!finite(m.to) || m.to < 0) {
+        recordUnknown("result_amount", m.path);
+        continue;
+      }
+      const delta = finite(m.from) && m.from >= 0 ? Math.abs(m.to - m.from) : void 0;
+      if (m.field === "total_budget.amount" && request.total_budget?.currency !== currency) {
+        if (currency === void 0) recordUnknown("currency", m.path);
+        else return exceeded("currency_mismatch", "total_budget.currency");
+      }
+      for (const key of ["max_delta_amount", "min_result_amount", "max_result_amount"]) {
+        const bound = c[key];
+        if (!bound) continue;
+        if (currency === void 0) {
+          recordUnknown("currency", m.path);
+          continue;
+        }
+        if (currency !== bound.currency) {
+          recordUnknown("currency_mismatch", m.path);
+          continue;
+        }
+        if (key === "max_delta_amount") {
+          if (delta === void 0) recordUnknown(key, m.path);
+          else if (delta > bound.amount) return exceeded(key, m.path);
+        } else if (key === "min_result_amount" && m.to < bound.amount || key === "max_result_amount" && m.to > bound.amount)
+          return exceeded(key, m.path);
+      }
+      if (c.max_delta_percent !== void 0) {
+        if (delta === void 0 || !finite(m.from)) recordUnknown("max_delta_percent", m.path);
+        else if (m.from === 0 ? delta > 0 : delta * 100 > c.max_delta_percent * m.from)
+          return exceeded("max_delta_percent", m.path);
+      }
+    }
+  } else if (c.kind === "flight") {
+    if (!relevant.length) return unknown("cannot_preflight", term.action);
+    for (const m of relevant) {
+      const before = timestamp(m.from), after = timestamp(m.to);
+      if (after === void 0) {
+        recordUnknown("result_time", m.path);
+        continue;
+      }
+      if (c.max_change !== void 0) {
+        const max = (0, import_action_contracts.elapsedDuration)(c.max_change);
+        if (before === void 0 || max === void 0) recordUnknown("max_change", m.path);
+        else if (Math.abs(after - before) > max) return exceeded("max_change", m.path);
+      }
+      if (c.earliest_result !== void 0 && after < Date.parse(c.earliest_result))
+        return exceeded("earliest_result", m.path);
+      if (c.latest_result !== void 0 && after > Date.parse(c.latest_result))
+        return exceeded("latest_result", m.path);
+      if (c.minimum_notice !== void 0) {
+        if ((0, import_action_contracts.elapsedDuration)(c.minimum_notice) === void 0) recordUnknown("minimum_notice", m.path);
+        else return exceeded("minimum_notice", m.path);
+      }
+    }
+  } else if (c.kind === "package_count") {
+    const additions = request.new_packages?.length ?? 0;
+    const removed = request.packages?.filter((p) => p.canceled === true) ?? [];
+    const removals = removed.length;
+    if (c.max_additions !== void 0 && additions > c.max_additions) return exceeded("max_additions", "new_packages");
+    if (c.max_removals !== void 0 && removals > c.max_removals) return exceeded("max_removals", "packages");
+    if (c.max_result_count !== void 0) {
+      const current = buy.packages;
+      if (!current || new Set(current.map((p) => p.package_id)).size !== current.length || current.some((p) => !p.package_id) || new Set(removed.map((p) => p.package_id)).size !== removals || removed.some(
+        (p) => !current.some((old) => old.package_id === p.package_id && !old.canceled && old.status !== "canceled")
+      )) {
+        recordUnknown("max_result_count", "packages");
+      } else if (current.filter((p) => !p.canceled && p.status !== "canceled").length + additions - removals > c.max_result_count)
+        return exceeded("max_result_count", "packages");
+    }
+  } else if (c.kind === "effective_timing") {
+    const path = relevant[0]?.path ?? (term.action === "cancel" ? "canceled" : "paused");
+    if (c.minimum_notice !== void 0) {
+      if ((0, import_action_contracts.elapsedDuration)(c.minimum_notice) === void 0) recordUnknown("minimum_notice", path);
+      else return exceeded("minimum_notice", path);
+    }
+    if ((c.earliest_effective_at !== void 0 || c.latest_effective_at !== void 0) && !finite(options.now))
+      recordUnknown("request_time", path);
+    else if (finite(options.now)) {
+      if (c.earliest_effective_at !== void 0 && options.now < Date.parse(c.earliest_effective_at))
+        return exceeded("earliest_effective_at", path);
+      if (c.latest_effective_at !== void 0 && options.now > Date.parse(c.latest_effective_at))
+        return exceeded("latest_effective_at", path);
+    }
+  }
+  return unresolved ?? { status: "satisfied" };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  evaluateChangeTermConstraints
+});

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

@@ -0,0 +1,146 @@
+import { changeConstraintIssues, elapsedDuration } from "./action-contracts.mjs";
+const finite = (value) => typeof value === "number" && Number.isFinite(value);
+const timestamp = (value) => {
+  const raw = typeof value === "object" && value !== null && "datetime" in value ? value.datetime : value;
+  if (typeof raw !== "string") return void 0;
+  const parsed = Date.parse(raw);
+  return Number.isFinite(parsed) ? parsed : void 0;
+};
+const unknown = (constraint, path) => ({
+  status: "unknown",
+  constraint,
+  path,
+  message: `Cannot evaluate ${constraint} at ${path}; supply the committed baseline, currency, and captured request time required by that bound.`
+});
+const exceeded = (constraint, path) => ({
+  status: "exceeded",
+  constraint,
+  path,
+  message: "The requested change exceeds the accepted bound; refine the accepted proposal."
+});
+function evaluateChangeTermConstraints(term, buy, request, mutations, options = {}) {
+  if (request.total_budget && mutations.some((m) => m.action === term.action && ["total_budget.amount", "budget_allocation"].includes(m.field))) {
+    const currency = typeof buy.total_budget === "object" ? buy.total_budget?.currency : buy.currency;
+    if (currency === void 0) return unknown("currency", "total_budget.currency");
+    if (request.total_budget.currency !== currency) return exceeded("currency_mismatch", "total_budget.currency");
+  }
+  if (term.constraints === void 0) return { status: "satisfied" };
+  if (changeConstraintIssues(term.action, term.constraints).length) return unknown("invalid_constraints", term.action);
+  const c = term.constraints;
+  const relevant = mutations.filter((m) => m.action === term.action);
+  let unresolved;
+  const recordUnknown = (key, path) => {
+    unresolved ??= unknown(key, path);
+  };
+  if (c.kind === "budget") {
+    if (request.new_packages?.length && (c.min_result_amount || c.max_result_amount))
+      return unknown("added_package_budget", "new_packages");
+    const values = relevant.filter((m) => /(?:budget(?:\.amount)?|daily_budget_cap|min_spend_target)$/.test(m.field));
+    if (!values.length && term.action === "update_budget_allocation" && relevant.some((m) => m.field === "budget_allocation")) {
+      const amount = typeof buy.total_budget === "object" ? buy.total_budget?.amount : buy.total_budget;
+      values.push({
+        action: term.action,
+        field: "budget_allocation",
+        path: "budget_allocation",
+        scope: "buy",
+        from: amount,
+        to: request.total_budget?.amount ?? amount
+      });
+    }
+    if (!values.length) return unknown("cannot_preflight", term.action);
+    const currency = typeof buy.total_budget === "object" ? buy.total_budget?.currency : buy.currency;
+    for (const m of values) {
+      if (m.to === null && (m.field === "packages[].budget" || m.field.endsWith("daily_budget_cap")) && term.action === "increase_budget") {
+        if (c.max_delta_amount || c.max_delta_percent !== void 0 || c.max_result_amount)
+          return exceeded("unbounded_result", m.path);
+        continue;
+      }
+      if (!finite(m.to) || m.to < 0) {
+        recordUnknown("result_amount", m.path);
+        continue;
+      }
+      const delta = finite(m.from) && m.from >= 0 ? Math.abs(m.to - m.from) : void 0;
+      if (m.field === "total_budget.amount" && request.total_budget?.currency !== currency) {
+        if (currency === void 0) recordUnknown("currency", m.path);
+        else return exceeded("currency_mismatch", "total_budget.currency");
+      }
+      for (const key of ["max_delta_amount", "min_result_amount", "max_result_amount"]) {
+        const bound = c[key];
+        if (!bound) continue;
+        if (currency === void 0) {
+          recordUnknown("currency", m.path);
+          continue;
+        }
+        if (currency !== bound.currency) {
+          recordUnknown("currency_mismatch", m.path);
+          continue;
+        }
+        if (key === "max_delta_amount") {
+          if (delta === void 0) recordUnknown(key, m.path);
+          else if (delta > bound.amount) return exceeded(key, m.path);
+        } else if (key === "min_result_amount" && m.to < bound.amount || key === "max_result_amount" && m.to > bound.amount)
+          return exceeded(key, m.path);
+      }
+      if (c.max_delta_percent !== void 0) {
+        if (delta === void 0 || !finite(m.from)) recordUnknown("max_delta_percent", m.path);
+        else if (m.from === 0 ? delta > 0 : delta * 100 > c.max_delta_percent * m.from)
+          return exceeded("max_delta_percent", m.path);
+      }
+    }
+  } else if (c.kind === "flight") {
+    if (!relevant.length) return unknown("cannot_preflight", term.action);
+    for (const m of relevant) {
+      const before = timestamp(m.from), after = timestamp(m.to);
+      if (after === void 0) {
+        recordUnknown("result_time", m.path);
+        continue;
+      }
+      if (c.max_change !== void 0) {
+        const max = elapsedDuration(c.max_change);
+        if (before === void 0 || max === void 0) recordUnknown("max_change", m.path);
+        else if (Math.abs(after - before) > max) return exceeded("max_change", m.path);
+      }
+      if (c.earliest_result !== void 0 && after < Date.parse(c.earliest_result))
+        return exceeded("earliest_result", m.path);
+      if (c.latest_result !== void 0 && after > Date.parse(c.latest_result))
+        return exceeded("latest_result", m.path);
+      if (c.minimum_notice !== void 0) {
+        if (elapsedDuration(c.minimum_notice) === void 0) recordUnknown("minimum_notice", m.path);
+        else return exceeded("minimum_notice", m.path);
+      }
+    }
+  } else if (c.kind === "package_count") {
+    const additions = request.new_packages?.length ?? 0;
+    const removed = request.packages?.filter((p) => p.canceled === true) ?? [];
+    const removals = removed.length;
+    if (c.max_additions !== void 0 && additions > c.max_additions) return exceeded("max_additions", "new_packages");
+    if (c.max_removals !== void 0 && removals > c.max_removals) return exceeded("max_removals", "packages");
+    if (c.max_result_count !== void 0) {
+      const current = buy.packages;
+      if (!current || new Set(current.map((p) => p.package_id)).size !== current.length || current.some((p) => !p.package_id) || new Set(removed.map((p) => p.package_id)).size !== removals || removed.some(
+        (p) => !current.some((old) => old.package_id === p.package_id && !old.canceled && old.status !== "canceled")
+      )) {
+        recordUnknown("max_result_count", "packages");
+      } else if (current.filter((p) => !p.canceled && p.status !== "canceled").length + additions - removals > c.max_result_count)
+        return exceeded("max_result_count", "packages");
+    }
+  } else if (c.kind === "effective_timing") {
+    const path = relevant[0]?.path ?? (term.action === "cancel" ? "canceled" : "paused");
+    if (c.minimum_notice !== void 0) {
+      if (elapsedDuration(c.minimum_notice) === void 0) recordUnknown("minimum_notice", path);
+      else return exceeded("minimum_notice", path);
+    }
+    if ((c.earliest_effective_at !== void 0 || c.latest_effective_at !== void 0) && !finite(options.now))
+      recordUnknown("request_time", path);
+    else if (finite(options.now)) {
+      if (c.earliest_effective_at !== void 0 && options.now < Date.parse(c.earliest_effective_at))
+        return exceeded("earliest_effective_at", path);
+      if (c.latest_effective_at !== void 0 && options.now > Date.parse(c.latest_effective_at))
+        return exceeded("latest_effective_at", path);
+    }
+  }
+  return unresolved ?? { status: "satisfied" };
+}
+export {
+  evaluateChangeTermConstraints
+};

package/dist/lib/media-buy/action-contracts.d.mts

@@ -0,0 +1,40 @@
+import type { ActionBuy, LiveMediaBuyAction, ActionProposal, MediaBuyAction, MediaBuyTask, ProposalChangeTerm, ProductActionTemplate, MediaBuyStatus } from './action-types.mjs';
+import type { SLAWindow } from './types.mjs';
+export declare const NON_TERMINAL_ACTION_STATUSES: readonly ["pending_creatives", "pending_start", "active", "paused"];
+/** Canonical task alternatives. The live entry chooses among these; mode never selects a task. */
+export declare function mediaBuyActionTasks(action: string): readonly MediaBuyTask[];
+/** The canonical default, only usable with a known current right and validated live entry. */
+export declare function defaultMediaBuyActionTask(action: MediaBuyAction): MediaBuyTask | undefined;
+export declare function actionAllowedStatuses(term: Pick<ProposalChangeTerm, 'action' | 'allowed_statuses'>): MediaBuyStatus[];
+/** Elapsed durations only. Calendar/campaign lengths require seller state and remain unknown. */
+export declare function elapsedDuration(value: unknown): number | undefined;
+/** Runtime may retain or tighten elapsed maxima; absent committed maxima cannot be dropped. */
+export declare function slaWithin(ceiling: SLAWindow | undefined, candidate: SLAWindow | undefined): boolean;
+/** Structural/action checks for this pure helper, not a replacement for proposal schema/digest verification. */
+export declare function changeConstraintIssues(action: MediaBuyAction, constraints: unknown, currency?: string): string[];
+export declare function slaValid(sla: unknown): boolean;
+export declare function changeTermIssues(terms: readonly ProposalChangeTerm[], currency?: string): string[];
+export declare function productTemplateIssues(templates: readonly ProductActionTemplate[], currency?: string): string[];
+/** Match advisory rollups only; accepted rights always retain exact canonical identity. */
+export declare function findProductAction(templates: readonly ProductActionTemplate[] | undefined, action: MediaBuyAction): ProductActionTemplate | undefined;
+export declare function legacyActionSupported(action: string): boolean;
+/** Structural live-entry validation; unknown action/mode strings remain opaque. */
+export declare function liveActionIssues(entries: unknown): string[];
+/** beta.9 introduced change_term_id, seller_managed and condition_unresolved together (upstream a1672f9). */
+export declare function supportsChangeTermIdentity(version: string): boolean;
+/** rc.3 added shared-cap rights and exact live package scope. */
+export declare function supportsRc3Actions(version: string): boolean;
+/** Check wire feature introductions independently of whether an action has commercial terms. */
+export declare function liveActionFitsVersion(entry: LiveMediaBuyAction, version: string): boolean;
+/** Narrow error-details vocabulary is distinct from canonical actions; older served versions stay gated. */
+export declare function actionFitsErrorDetails(action: string, version: string): boolean;
+/** Apply a separately stored accepted snapshot before either decomposition or assessment. */
+export declare function withActionProposal<T extends ActionBuy>(buy: T, options: {
+    proposal?: ActionProposal;
+}): T;
+/** Explicit terminal, pending, or unknown package state takes precedence over pause flags. */
+export declare function packageActionStatus(pkg: {
+    status?: string;
+    canceled?: boolean;
+    paused?: boolean;
+} | undefined): string | undefined;

package/dist/lib/media-buy/action-contracts.d.ts

@@ -0,0 +1,40 @@
+import type { ActionBuy, LiveMediaBuyAction, ActionProposal, MediaBuyAction, MediaBuyTask, ProposalChangeTerm, ProductActionTemplate, MediaBuyStatus } from './action-types';
+import type { SLAWindow } from './types';
+export declare const NON_TERMINAL_ACTION_STATUSES: readonly ["pending_creatives", "pending_start", "active", "paused"];
+/** Canonical task alternatives. The live entry chooses among these; mode never selects a task. */
+export declare function mediaBuyActionTasks(action: string): readonly MediaBuyTask[];
+/** The canonical default, only usable with a known current right and validated live entry. */
+export declare function defaultMediaBuyActionTask(action: MediaBuyAction): MediaBuyTask | undefined;
+export declare function actionAllowedStatuses(term: Pick<ProposalChangeTerm, 'action' | 'allowed_statuses'>): MediaBuyStatus[];
+/** Elapsed durations only. Calendar/campaign lengths require seller state and remain unknown. */
+export declare function elapsedDuration(value: unknown): number | undefined;
+/** Runtime may retain or tighten elapsed maxima; absent committed maxima cannot be dropped. */
+export declare function slaWithin(ceiling: SLAWindow | undefined, candidate: SLAWindow | undefined): boolean;
+/** Structural/action checks for this pure helper, not a replacement for proposal schema/digest verification. */
+export declare function changeConstraintIssues(action: MediaBuyAction, constraints: unknown, currency?: string): string[];
+export declare function slaValid(sla: unknown): boolean;
+export declare function changeTermIssues(terms: readonly ProposalChangeTerm[], currency?: string): string[];
+export declare function productTemplateIssues(templates: readonly ProductActionTemplate[], currency?: string): string[];
+/** Match advisory rollups only; accepted rights always retain exact canonical identity. */
+export declare function findProductAction(templates: readonly ProductActionTemplate[] | undefined, action: MediaBuyAction): ProductActionTemplate | undefined;
+export declare function legacyActionSupported(action: string): boolean;
+/** Structural live-entry validation; unknown action/mode strings remain opaque. */
+export declare function liveActionIssues(entries: unknown): string[];
+/** beta.9 introduced change_term_id, seller_managed and condition_unresolved together (upstream a1672f9). */
+export declare function supportsChangeTermIdentity(version: string): boolean;
+/** rc.3 added shared-cap rights and exact live package scope. */
+export declare function supportsRc3Actions(version: string): boolean;
+/** Check wire feature introductions independently of whether an action has commercial terms. */
+export declare function liveActionFitsVersion(entry: LiveMediaBuyAction, version: string): boolean;
+/** Narrow error-details vocabulary is distinct from canonical actions; older served versions stay gated. */
+export declare function actionFitsErrorDetails(action: string, version: string): boolean;
+/** Apply a separately stored accepted snapshot before either decomposition or assessment. */
+export declare function withActionProposal<T extends ActionBuy>(buy: T, options: {
+    proposal?: ActionProposal;
+}): T;
+/** Explicit terminal, pending, or unknown package state takes precedence over pause flags. */
+export declare function packageActionStatus(pkg: {
+    status?: string;
+    canceled?: boolean;
+    paused?: boolean;
+} | undefined): string | undefined;