@adcp/sdk 16.2.0 → 16.4.0

package/dist/lib/core/TaskExecutor.mjs

@@ -28,7 +28,9 @@ import {
 } from "../validation/client-hooks.mjs";
 import { formatIssues } from "../validation/schema-validator.mjs";
 import { withServedValidationVersion } from "../validation/schema-loader.mjs";
-import { ADCP_VERSION } from "../version.mjs";
+import { ADCP_VERSION, toReleasePrecisionVersion } from "../version.mjs";
+import { applicableRefinementServedVersion } from "../negotiation/version.mjs";
+import { selectRefinementSchemaVersion } from "../negotiation/verification.mjs";
 import { unwrapProtocolResponse, isAdcpOperationSuccess } from "../utils/response-unwrapper.mjs";
 import { extractAdcpErrorInfo, extractCorrelationId } from "../utils/error-extraction.mjs";
 import { generateIdempotencyKey, requestUsesIdempotency, redactIdempotencyKeyInArgs } from "../utils/idempotency.mjs";
@@ -665,7 +667,11 @@ class TaskExecutor {
    * adaptation runs, so the validator sees the same object the caller wrote.
    * Throws in strict, logs to `debugLogs` in warn, no-ops in off.
    */
-  validateRequest(taskName, params, debugLogs) {
+  validateRequest(taskName, params, debugLogs, adcpVersion) {
+    if (adcpVersion !== void 0) {
+      validateOutgoingRequest(taskName, params, this.requestValidationMode, debugLogs, adcpVersion);
+      return;
+    }
     if (this.config.experimentalIdentity33?.() && this.requestValidationMode !== "off") {
       const outcome = validateIdentity33Payload(taskName, "request", params, this.config.adcpVersion);
       if (!outcome.valid) {
@@ -801,6 +807,13 @@ class TaskExecutor {
       agent: { id: agent.id, name: agent.name, protocol: agent.protocol },
       serverVersion: effectiveServerVersion,
       serverVersionSynthetic: targetCapabilities?._synthetic ?? serverVersion === void 0,
+      ...taskName === "refine_proposals" && targetCapabilities?._synthetic === false && {
+        refinementServedVersion: applicableRefinementServedVersion(
+          targetCapabilities.servedVersion,
+          params?.adcp_version ?? toReleasePrecisionVersion(wireAdcpVersion ?? this.config.adcpVersion ?? ADCP_VERSION),
+          toReleasePrecisionVersion(this.config.wireAdcpVersion ?? this.config.adcpVersion ?? ADCP_VERSION)
+        )
+      },
       idempotencyKey
     };
     this.activeTasks.set(taskId, taskState);
@@ -1091,7 +1104,8 @@ class TaskExecutor {
         dispatchSettlement?.persistPausedContinuation ?? true,
         effectiveServerVersion,
         deferredClientContext,
-        dispatchSettlement?.requireDeferredSettlementResumeAuthorization === true
+        dispatchSettlement?.requireDeferredSettlementResumeAuthorization === true,
+        taskState.refinementServedVersion
       );
       throwIfAborted(postDispatchOptions.signal);
       if (governanceResult) {
@@ -1234,17 +1248,36 @@ class TaskExecutor {
       debug_logs: debugLogs
     };
   }
-  async handleAsyncResponse(agent, taskId, taskName, params, response, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false) {
+  async handleAsyncResponse(agent, taskId, taskName, params, response, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false, refinementServedVersion) {
     const status = this.responseParser.getStatus(response);
     const serverTaskId = this.responseParser.getTaskId(response);
     const task = this.activeTasks.get(taskId);
     if (task && serverTaskId) task.serverTaskId = serverTaskId;
     switch (status) {
       case ADCP_STATUS.COMPLETED:
-        const completedData = this.extractResponseData(response, debugLogs, taskName, serverVersion);
+        const completedData = this.extractResponseData(
+          response,
+          debugLogs,
+          taskName,
+          serverVersion,
+          options.negotiatedAdcpVersion
+        );
         if (!deferTerminalTaskStatus) this.updateTaskStatus(taskId, "completed", completedData);
-        const operationSuccess = this.isOperationSuccess(completedData, taskName, serverVersion);
-        const validationResult = this.validateResponseSchema(completedData, taskName, debugLogs, serverVersion);
+        const operationSuccess = this.isOperationSuccess(
+          completedData,
+          taskName,
+          serverVersion,
+          options.negotiatedAdcpVersion
+        );
+        const validationResult = this.validateResponseSchema(
+          completedData,
+          taskName,
+          debugLogs,
+          serverVersion,
+          params,
+          refinementServedVersion,
+          options.negotiatedAdcpVersion
+        );
         const finalSuccess = operationSuccess && validationResult.valid;
         const finalError = !finalSuccess ? validationResult.errors.length > 0 ? `Schema validation failed: ${validationResult.errors.join("; ")}` : this.extractOperationError(completedData) : void 0;
         if (finalSuccess) {
@@ -1329,12 +1362,19 @@ class TaskExecutor {
           persistPausedContinuation,
           serverVersion,
           deferredClientContext,
-          requireDeferredSettlementResumeAuthorization
+          requireDeferredSettlementResumeAuthorization,
+          refinementServedVersion
         );
       case ADCP_STATUS.FAILED:
       case ADCP_STATUS.REJECTED:
       case ADCP_STATUS.CANCELED: {
-        const failedData = this.extractResponseData(response, debugLogs, taskName, serverVersion);
+        const failedData = this.extractResponseData(
+          response,
+          debugLogs,
+          taskName,
+          serverVersion,
+          options.negotiatedAdcpVersion
+        );
         const failedPayload = response?.structuredContent === void 0 && response?.content === void 0 && response?.result === void 0 && response?.data != null && typeof response.data === "object" ? response.data : failedData;
         const adcpErrorInfo = extractAdcpErrorInfo(failedPayload);
         const hasStructuredError = !!adcpErrorInfo;
@@ -1362,10 +1402,29 @@ class TaskExecutor {
         };
       }
       default:
-        const defaultData = this.extractResponseData(response, debugLogs, taskName, serverVersion);
+        const defaultData = this.extractResponseData(
+          response,
+          debugLogs,
+          taskName,
+          serverVersion,
+          options.negotiatedAdcpVersion
+        );
         if (defaultData && (defaultData !== response || response.structuredContent || response.result || response.data)) {
-          const defaultSuccess = this.isOperationSuccess(defaultData, taskName, serverVersion);
-          const defaultValidation = this.validateResponseSchema(defaultData, taskName, debugLogs, serverVersion);
+          const defaultSuccess = this.isOperationSuccess(
+            defaultData,
+            taskName,
+            serverVersion,
+            options.negotiatedAdcpVersion
+          );
+          const defaultValidation = this.validateResponseSchema(
+            defaultData,
+            taskName,
+            debugLogs,
+            serverVersion,
+            params,
+            refinementServedVersion,
+            options.negotiatedAdcpVersion
+          );
           const defaultFinalSuccess = defaultSuccess && defaultValidation.valid;
           const defaultFinalError = !defaultFinalSuccess ? defaultValidation.errors.length > 0 ? `Schema validation failed: ${defaultValidation.errors.join("; ")}` : this.extractOperationError(defaultData) : void 0;
           if (defaultFinalSuccess) {
@@ -1415,7 +1474,7 @@ class TaskExecutor {
    *
    * @internal Exposed for testing purposes
    */
-  extractResponseData(response, debugLogs, toolName, serverVersion) {
+  extractResponseData(response, debugLogs, toolName, serverVersion, negotiatedAdcpVersion) {
     const a2aState = response?.result?.status?.state;
     if (a2aState === "input-required" || a2aState === "auth-required") {
       const statusParts = response?.result?.status?.message?.parts;
@@ -1456,7 +1515,7 @@ class TaskExecutor {
       }
       const unwrapped = unwrapProtocolResponse(response, toolName, void 0, {
         filterInvalidProducts: this.config.filterInvalidProducts,
-        responseAdcpVersion: this.effectiveResponseAdcpVersion(serverVersion)
+        responseAdcpVersion: this.effectiveResponseAdcpVersion(serverVersion, negotiatedAdcpVersion)
       });
       if (response?.structuredContent) {
         this.logDebug(debugLogs, "info", "Successfully extracted MCP data", {
@@ -1487,8 +1546,12 @@ class TaskExecutor {
    * Check if extracted response data represents a successful operation.
    * Handles singular `error`, plural `errors` (AdCP schema), and `success: false`.
    */
-  isOperationSuccess(data, taskName, serverVersion) {
-    return isAdcpOperationSuccess(data, taskName, this.effectiveResponseAdcpVersion(serverVersion));
+  isOperationSuccess(data, taskName, serverVersion, negotiatedAdcpVersion) {
+    return isAdcpOperationSuccess(
+      data,
+      taskName,
+      this.effectiveResponseAdcpVersion(serverVersion, negotiatedAdcpVersion)
+    );
   }
   /**
    * Extract a human-readable error message from response data.
@@ -1519,7 +1582,13 @@ class TaskExecutor {
    * Handle 'working' status - return as valid intermediate state
    */
   async waitForWorkingCompletion(agent, taskId, taskName, params, initialResponse, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), serverVersion = "v3") {
-    const partialData = this.extractResponseData(initialResponse, debugLogs, taskName, serverVersion);
+    const partialData = this.extractResponseData(
+      initialResponse,
+      debugLogs,
+      taskName,
+      serverVersion,
+      options.negotiatedAdcpVersion
+    );
     const metadata = this.buildMetadata({
       taskId,
       taskName,
@@ -1543,7 +1612,13 @@ class TaskExecutor {
    * Set up submitted task with webhook
    */
   async setupSubmittedTask(agent, taskId, taskName, response, messages, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, serverVersion = "v3") {
-    const partialData = this.extractResponseData(response, debugLogs, taskName, serverVersion);
+    const partialData = this.extractResponseData(
+      response,
+      debugLogs,
+      taskName,
+      serverVersion,
+      options.negotiatedAdcpVersion
+    );
     let webhookUrl = response.webhookUrl;
     if (!webhookUrl && this.config.webhookManager) {
       webhookUrl = this.config.webhookManager.generateUrl(taskId);
@@ -1979,7 +2054,7 @@ class TaskExecutor {
    * This is common for HITL (human-in-the-loop) workflows where the agent has already processed
    * the request and is just signaling that async approval may be needed.
    */
-  async handleInputRequired(agent, taskId, taskName, params, response, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, pauseStatus = "input-required", persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false) {
+  async handleInputRequired(agent, taskId, taskName, params, response, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, pauseStatus = "input-required", persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false, refinementServedVersion) {
     const inputRequest = this.responseParser.parseInputRequest(response);
     const serverContextId = this.responseParser.getContextId(response) ?? response.contextId;
     const a2aTaskId = this.responseParser.getA2AContinuationTaskId(response);
@@ -1987,7 +2062,13 @@ class TaskExecutor {
     const operationRoutedContinuation = deferTerminalTaskStatus || directContinuationRecovery;
     const settlementServerTaskId = operationRoutedContinuation ? this.responseParser.getTaskId(response) : void 0;
     if (agent.protocol === "mcp" || !a2aTaskId) {
-      const partialData = this.extractResponseData(response, debugLogs, taskName, serverVersion);
+      const partialData = this.extractResponseData(
+        response,
+        debugLogs,
+        taskName,
+        serverVersion,
+        options.negotiatedAdcpVersion
+      );
       const metadata = this.buildMetadata({
         taskId,
         taskName,
@@ -2008,7 +2089,13 @@ class TaskExecutor {
       };
     }
     if (!inputHandler) {
-      const partialData = this.extractResponseData(response, debugLogs, taskName, serverVersion);
+      const partialData = this.extractResponseData(
+        response,
+        debugLogs,
+        taskName,
+        serverVersion,
+        options.negotiatedAdcpVersion
+      );
       const metadata = this.buildMetadata({
         taskId,
         taskName,
@@ -2035,8 +2122,12 @@ class TaskExecutor {
           a2aTaskId,
           serverVersion,
           ...options.wireAdcpVersion !== void 0 && { wireAdcpVersion: options.wireAdcpVersion },
+          ...options.negotiatedAdcpVersion !== void 0 && {
+            negotiatedAdcpVersion: options.negotiatedAdcpVersion
+          },
           ...options.versionEnvelope !== void 0 && { versionEnvelope: options.versionEnvelope },
           serverVersionSynthetic: this.activeTasks.get(taskId)?.serverVersionSynthetic,
+          ...refinementServedVersion !== void 0 && { refinementServedVersion },
           agentId: agent.id,
           taskName,
           params: durableDeferredSnapshot(params),
@@ -2101,7 +2192,8 @@ class TaskExecutor {
           persistPausedContinuation,
           serverVersion,
           deferredClientContext,
-          requireDeferredSettlementResumeAuthorization
+          requireDeferredSettlementResumeAuthorization,
+          refinementServedVersion
         );
       };
       const deferred = {
@@ -2177,8 +2269,12 @@ class TaskExecutor {
           a2aTaskId,
           serverVersion,
           ...options.wireAdcpVersion !== void 0 && { wireAdcpVersion: options.wireAdcpVersion },
+          ...options.negotiatedAdcpVersion !== void 0 && {
+            negotiatedAdcpVersion: options.negotiatedAdcpVersion
+          },
           ...options.versionEnvelope !== void 0 && { versionEnvelope: options.versionEnvelope },
           serverVersionSynthetic: this.activeTasks.get(taskId)?.serverVersionSynthetic,
+          ...refinementServedVersion !== void 0 && { refinementServedVersion },
           agentId: agent.id,
           taskName,
           params: durableDeferredSnapshot(params),
@@ -2244,7 +2340,8 @@ class TaskExecutor {
           persistPausedContinuation,
           serverVersion,
           deferredClientContext,
-          requireDeferredSettlementResumeAuthorization
+          requireDeferredSettlementResumeAuthorization,
+          refinementServedVersion
         );
       };
       const deferred = {
@@ -2295,7 +2392,8 @@ class TaskExecutor {
       persistPausedContinuation,
       serverVersion,
       deferredClientContext,
-      requireDeferredSettlementResumeAuthorization
+      requireDeferredSettlementResumeAuthorization,
+      refinementServedVersion
     );
   }
   /**
@@ -2511,7 +2609,12 @@ class TaskExecutor {
         });
       }
       if (status.status === ADCP_STATUS.COMPLETED) {
-        const pollSuccess = this.isOperationSuccess(status.result, status.taskType, serverVersion);
+        const pollSuccess = this.isOperationSuccess(
+          status.result,
+          status.taskType,
+          serverVersion,
+          metadataTaskId ? this.activeTasks.get(metadataTaskId)?.options.negotiatedAdcpVersion : void 0
+        );
         if (pollSuccess) {
           return markAuthoritativePolledTerminal(
             attachMatch({
@@ -3066,6 +3169,7 @@ class TaskExecutor {
         state.messages,
         {
           ...state.wireAdcpVersion !== void 0 && { wireAdcpVersion: state.wireAdcpVersion },
+          ...state.negotiatedAdcpVersion !== void 0 && { negotiatedAdcpVersion: state.negotiatedAdcpVersion },
           ...state.versionEnvelope !== void 0 && { versionEnvelope: state.versionEnvelope }
         },
         [],
@@ -3287,6 +3391,7 @@ class TaskExecutor {
         // No handler for deferred tasks - input was provided by human
         {
           ...state.wireAdcpVersion !== void 0 && { wireAdcpVersion: state.wireAdcpVersion },
+          ...state.negotiatedAdcpVersion !== void 0 && { negotiatedAdcpVersion: state.negotiatedAdcpVersion },
           ...state.versionEnvelope !== void 0 && { versionEnvelope: state.versionEnvelope }
         },
         [],
@@ -3295,7 +3400,8 @@ class TaskExecutor {
         false,
         state.serverVersion,
         state.clientContext,
-        state.settlementResumeAuthorizationRequired === true
+        state.settlementResumeAuthorizationRequired === true,
+        state.refinementServedVersion
       );
       resumed = attachDeferredServerVersion(resumed, state);
       const observedResumedServerTaskId = resumed.metadata.serverTaskId;
@@ -3321,7 +3427,11 @@ class TaskExecutor {
           ...resumed.metadata.contextId !== void 0 ? { contextId: resumed.metadata.contextId } : state.contextId !== void 0 ? { contextId: state.contextId } : {},
           a2aTaskId: nextA2ATaskId,
           serverVersion: state.serverVersion,
+          ...state.refinementServedVersion !== void 0 && {
+            refinementServedVersion: state.refinementServedVersion
+          },
           ...state.wireAdcpVersion !== void 0 && { wireAdcpVersion: state.wireAdcpVersion },
+          ...state.negotiatedAdcpVersion !== void 0 && { negotiatedAdcpVersion: state.negotiatedAdcpVersion },
           ...state.versionEnvelope !== void 0 && { versionEnvelope: state.versionEnvelope },
           ...state.serverVersionSynthetic !== void 0 && {
             serverVersionSynthetic: state.serverVersionSynthetic
@@ -4249,7 +4359,7 @@ class TaskExecutor {
   /**
    * Continue a task after receiving input
    */
-  async continueTaskWithInput(agent, taskId, taskName, params, contextId, a2aTaskId, input, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false) {
+  async continueTaskWithInput(agent, taskId, taskName, params, contextId, a2aTaskId, input, messages, inputHandler, options = {}, debugLogs = [], startTime = Date.now(), deferTerminalTaskStatus = false, persistPausedContinuation = true, serverVersion = "v3", deferredClientContext, requireDeferredSettlementResumeAuthorization = false, refinementServedVersion) {
     const inputSnapshot = structuredClone(input);
     if (agent.protocol !== "a2a") {
       throw new Error("MCP does not define a standard continuation for a returned input-required task.");
@@ -4315,7 +4425,8 @@ class TaskExecutor {
       persistPausedContinuation,
       serverVersion,
       deferredClientContext,
-      requireDeferredSettlementResumeAuthorization
+      requireDeferredSettlementResumeAuthorization,
+      refinementServedVersion
     );
   }
   /**
@@ -4507,11 +4618,11 @@ class TaskExecutor {
    * valid so the caller can continue. Off mode short-circuits before
    * AJV runs.
    */
-  validateResponseSchema(response, taskName, debugLogs, serverVersion) {
+  validateResponseSchema(response, taskName, debugLogs, serverVersion, requestParams, refinementServedVersion, negotiatedAdcpVersion) {
     const mode = this.responseValidationMode;
     const logViolations = this.config.logSchemaViolations !== false;
     try {
-      const pinnedValidationVersion = this.responseAdcpVersionForValidation() ?? this.config.adcpVersion ?? ADCP_VERSION;
+      const pinnedValidationVersion = this.responseAdcpVersionForValidation() ?? negotiatedAdcpVersion ?? this.config.adcpVersion ?? ADCP_VERSION;
       if (taskName === "get_adcp_capabilities") {
         return withServedValidationVersion(
           response,
@@ -4519,6 +4630,46 @@ class TaskExecutor {
           (validationVersion) => this.validateResponseSchemaAgainst(response, taskName, debugLogs, mode, logViolations, validationVersion)
         );
       }
+      if (taskName === "refine_proposals" && mode !== "off") {
+        const ceiling = requestParams?.adcp_version ?? toReleasePrecisionVersion(this.config.wireAdcpVersion ?? pinnedValidationVersion);
+        const issues = [];
+        const selected = selectRefinementSchemaVersion(
+          ceiling,
+          response,
+          {
+            adcpVersion: pinnedValidationVersion,
+            servedAdcpVersion: applicableRefinementServedVersion(refinementServedVersion, ceiling)
+          },
+          issues
+        );
+        if (!selected) {
+          const errors = issues.map((issue) => `${issue.path}: ${issue.message}`);
+          if (logViolations) {
+            debugLogs.push({
+              timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+              type: mode === "strict" ? "error" : "warning",
+              message: `Schema validation ${mode === "strict" ? "failed" : "warning"} for ${taskName}: ${errors.join("; ")}`,
+              errors,
+              issues,
+              schemaVersion: pinnedValidationVersion,
+              mode
+            });
+            if (mode === "warn") {
+              console.warn(
+                `Schema validation failed for ${taskName} against AdCP ${pinnedValidationVersion} (non-blocking):`,
+                errors
+              );
+            } else {
+              console.error(
+                `Schema validation failed for ${taskName} against AdCP ${pinnedValidationVersion}:`,
+                errors
+              );
+            }
+          }
+          return { valid: mode !== "strict", errors: mode === "strict" ? errors : [] };
+        }
+        return this.validateResponseSchemaAgainst(response, taskName, debugLogs, mode, logViolations, selected);
+      }
       return this.validateResponseSchemaAgainst(
         response,
         taskName,
@@ -4573,8 +4724,8 @@ class TaskExecutor {
     if (this.config.versionEnvelope === "major-only") return "3.0";
     return void 0;
   }
-  effectiveResponseAdcpVersion(serverVersion) {
-    return this.responseAdcpVersionForValidation() ?? this.config.adcpVersion ?? ADCP_VERSION;
+  effectiveResponseAdcpVersion(serverVersion, negotiatedAdcpVersion) {
+    return this.responseAdcpVersionForValidation() ?? negotiatedAdcpVersion ?? this.config.adcpVersion ?? ADCP_VERSION;
   }
   /**
    * Update task status and emit events

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

@@ -0,0 +1,36 @@
+/**
+ * Locating and rewriting account natural keys inside a request, for the
+ * client's `accountIdentityDowngrade: 'reduce'` bookkeeping.
+ *
+ * When a request reaches a seller on an older release, its account keys can
+ * lose fields the older release cannot express (AdCP 3.2's `operator_unit`,
+ * `currency`, `timezone` and `brand.countries`). The client records which
+ * reduced key each buyer key reached the seller with, refuses a second buyer
+ * key that would land on the same seller account, and keeps addressing the
+ * account by its reduced key after the seller upgrades, until the buyer moves
+ * it to the full key.
+ */
+import type { AccountReference } from '../types/index.mjs';
+type Path = ReadonlyArray<string | number>;
+/** The natural-key projection of an account reference or `sync_accounts` row. */
+export declare function naturalAccountKey(value: unknown): AccountReference | undefined;
+export interface AccountKeySite {
+    path: Path;
+    key: AccountReference;
+}
+/**
+ * Natural account keys in a request: every `account` object and every entry
+ * of an `accounts` array (sync_accounts rows, list filters), at any depth.
+ */
+export declare function accountKeySites(params: unknown): AccountKeySite[];
+export declare function valueAt(root: unknown, path: Path): unknown;
+/**
+ * Return `root` with the account key at `path` replaced by `reduced`: the
+ * reducible fields `reduced` lacks are removed and the rest of the object
+ * (billing, settings) is kept. Unchanged branches keep their identity.
+ */
+export declare function withReducedKeyAt<T>(root: T, path: Path, reduced: AccountReference): T;
+/** Fields present on `full` but absent from `reduced`, as account-relative paths. */
+export declare function reducedFields(full: AccountReference, reduced: AccountReference): string[];
+export declare function sameAccountKey(left: AccountReference, right: AccountReference): boolean;
+export {};

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

@@ -0,0 +1,36 @@
+/**
+ * Locating and rewriting account natural keys inside a request, for the
+ * client's `accountIdentityDowngrade: 'reduce'` bookkeeping.
+ *
+ * When a request reaches a seller on an older release, its account keys can
+ * lose fields the older release cannot express (AdCP 3.2's `operator_unit`,
+ * `currency`, `timezone` and `brand.countries`). The client records which
+ * reduced key each buyer key reached the seller with, refuses a second buyer
+ * key that would land on the same seller account, and keeps addressing the
+ * account by its reduced key after the seller upgrades, until the buyer moves
+ * it to the full key.
+ */
+import type { AccountReference } from '../types';
+type Path = ReadonlyArray<string | number>;
+/** The natural-key projection of an account reference or `sync_accounts` row. */
+export declare function naturalAccountKey(value: unknown): AccountReference | undefined;
+export interface AccountKeySite {
+    path: Path;
+    key: AccountReference;
+}
+/**
+ * Natural account keys in a request: every `account` object and every entry
+ * of an `accounts` array (sync_accounts rows, list filters), at any depth.
+ */
+export declare function accountKeySites(params: unknown): AccountKeySite[];
+export declare function valueAt(root: unknown, path: Path): unknown;
+/**
+ * Return `root` with the account key at `path` replaced by `reduced`: the
+ * reducible fields `reduced` lacks are removed and the rest of the object
+ * (billing, settings) is kept. Unchanged branches keep their identity.
+ */
+export declare function withReducedKeyAt<T>(root: T, path: Path, reduced: AccountReference): T;
+/** Fields present on `full` but absent from `reduced`, as account-relative paths. */
+export declare function reducedFields(full: AccountReference, reduced: AccountReference): string[];
+export declare function sameAccountKey(left: AccountReference, right: AccountReference): boolean;
+export {};

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

@@ -0,0 +1,127 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var account_reduction_exports = {};
+__export(account_reduction_exports, {
+  accountKeySites: () => accountKeySites,
+  naturalAccountKey: () => naturalAccountKey,
+  reducedFields: () => reducedFields,
+  sameAccountKey: () => sameAccountKey,
+  valueAt: () => valueAt,
+  withReducedKeyAt: () => withReducedKeyAt
+});
+module.exports = __toCommonJS(account_reduction_exports);
+var import_account_key = require('./account-key.js');
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+const REDUCIBLE_FIELDS = ["operator_unit", "currency", "timezone"];
+function naturalAccountKey(value) {
+  if (!isObject(value) || typeof value.account_id === "string") return void 0;
+  const brand = value.brand;
+  if (!isObject(brand) || typeof brand.domain !== "string" || typeof value.operator !== "string") return void 0;
+  return {
+    brand: {
+      domain: brand.domain,
+      ...typeof brand.brand_id === "string" && { brand_id: brand.brand_id },
+      ...Array.isArray(brand.countries) && { countries: brand.countries }
+    },
+    operator: value.operator,
+    ...isObject(value.operator_unit) && { operator_unit: value.operator_unit },
+    ...typeof value.currency === "string" && { currency: value.currency },
+    ...typeof value.timezone === "string" && { timezone: value.timezone },
+    ...typeof value.sandbox === "boolean" && { sandbox: value.sandbox }
+  };
+}
+function accountKeySites(params) {
+  const sites = [];
+  const visit = (value, path, depth) => {
+    if (depth > 8) return;
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => visit(item, [...path, index], depth + 1));
+      return;
+    }
+    if (!isObject(value)) return;
+    for (const [field, child] of Object.entries(value)) {
+      if (field === "account") {
+        const key = naturalAccountKey(child);
+        if (key) sites.push({ path: [...path, field], key });
+      } else if (field === "accounts" && Array.isArray(child)) {
+        child.forEach((entry, index) => {
+          const key = naturalAccountKey(entry);
+          if (key) sites.push({ path: [...path, field, index], key });
+        });
+      }
+      visit(child, [...path, field], depth + 1);
+    }
+  };
+  visit(params, [], 0);
+  return sites;
+}
+function valueAt(root, path) {
+  let current = root;
+  for (const segment of path) {
+    if (current === null || typeof current !== "object") return void 0;
+    current = current[segment];
+  }
+  return current;
+}
+function withReducedKeyAt(root, path, reduced) {
+  if (path.length === 0) {
+    if (!isObject(root) || "account_id" in reduced) return root;
+    const next = { ...root };
+    for (const field of REDUCIBLE_FIELDS) {
+      if (reduced[field] === void 0) delete next[field];
+    }
+    if (isObject(next.brand) && reduced.brand.countries === void 0 && "countries" in next.brand) {
+      const { countries: _, ...brand } = next.brand;
+      next.brand = brand;
+    }
+    return next;
+  }
+  const [head, ...rest] = path;
+  if (Array.isArray(root) && typeof head === "number") {
+    const copy = [...root];
+    copy[head] = withReducedKeyAt(copy[head], rest, reduced);
+    return copy;
+  }
+  if (isObject(root) && typeof head === "string") {
+    return { ...root, [head]: withReducedKeyAt(root[head], rest, reduced) };
+  }
+  return root;
+}
+function reducedFields(full, reduced) {
+  if ("account_id" in full || "account_id" in reduced) return [];
+  const fields = REDUCIBLE_FIELDS.filter(
+    (field) => full[field] !== void 0 && reduced[field] === void 0
+  );
+  if (full.brand.countries !== void 0 && reduced.brand.countries === void 0) fields.push("brand.countries");
+  return fields;
+}
+function sameAccountKey(left, right) {
+  return (0, import_account_key.accountReferenceKey)(left) === (0, import_account_key.accountReferenceKey)(right);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  accountKeySites,
+  naturalAccountKey,
+  reducedFields,
+  sameAccountKey,
+  valueAt,
+  withReducedKeyAt
+});