@adcp/sdk 14.0.0 → 14.2.0

package/dist/lib/server/create-adcp-server.js

@@ -58,6 +58,8 @@ var import_tool_request_schemas = require('../utils/tool-request-schemas.js');
 var import_seller = require('../negotiation/seller.js');
 var import_buyer = require('../negotiation/buyer.js');
 var import_verification = require('../negotiation/verification.js');
+var import_account_provisioning = require('./account-provisioning.js');
+var import_account_reference_warnings = require('./account-reference-warnings.js');
 var import_idempotency = require('../utils/idempotency.js');
 var import_envelope_status_compat = require('../utils/envelope-status-compat.js');
 var import_schema_validator = require('../validation/schema-validator.js');
@@ -584,6 +586,98 @@ function shallowToolInputHintSchema(toolName) {
   SHALLOW_HINT_SCHEMAS.set(toolName, schema);
   return schema;
 }
+function isAccountNotificationEventIssue(issue) {
+  return issue.keyword === "enum" && /^\/accounts\/\d+\/notification_configs\/\d+\/event_types\/\d+$/.test(issue.pointer);
+}
+function rejectedSyncAccountRow(entry) {
+  const identity = entry.account !== void 0 ? { account: entry.account } : Object.fromEntries(
+    ["brand", "operator", "operator_unit", "currency", "timezone", "sandbox"].filter((key) => entry[key] !== void 0).map((key) => [key, entry[key]])
+  );
+  return {
+    ...identity,
+    action: "failed",
+    // Provisioning was declined. A failed settings update does not establish
+    // the existing account's lifecycle state, so leave that status unknown.
+    ...entry.account === void 0 && { status: "rejected" },
+    errors: []
+  };
+}
+function accountNotificationFailureRows(accounts, issues, deleteMissing) {
+  const rows = /* @__PURE__ */ new Map();
+  for (const issue of issues) {
+    const [, accountIndex, configIndex, eventIndex] = issue.pointer.match(
+      /^\/accounts\/(\d+)\/notification_configs\/(\d+)\/event_types\/(\d+)$/
+    );
+    const index = Number(accountIndex);
+    const entry = accounts[index];
+    let row = rows.get(index);
+    if (row === void 0) {
+      row = rejectedSyncAccountRow(entry);
+      rows.set(index, row);
+    }
+    row.errors.push({
+      code: "VALIDATION_ERROR",
+      recovery: "correctable",
+      message: issue.message,
+      field: `notification_configs[${configIndex}].event_types[${eventIndex}]`
+    });
+  }
+  if (deleteMissing) {
+    for (const [index, entry] of accounts.entries()) {
+      if (rows.has(index)) continue;
+      rows.set(index, {
+        ...rejectedSyncAccountRow(entry),
+        errors: [
+          {
+            code: "VALIDATION_ERROR",
+            recovery: "correctable",
+            message: "delete_missing cannot be applied while account notification event types are invalid. Correct the rejected entries and retry.",
+            field: "delete_missing"
+          }
+        ]
+      });
+    }
+  }
+  return rows;
+}
+function restoreSyncAccountErrorIndices(row, acceptedIndices) {
+  if (!isPlainObject(row)) return row;
+  const restorePath = (path, pointer = false) => {
+    const match = pointer ? /^\/accounts\/(\d+)(?=\/|$)/.exec(path) : /^accounts\[(\d+)\](?=\.|\[|$)/.exec(path);
+    if (match === null) return path;
+    const originalIndex = acceptedIndices[Number(match[1])];
+    if (originalIndex === void 0) return path;
+    return `${pointer ? `/accounts/${originalIndex}` : `accounts[${originalIndex}]`}${path.slice(match[0].length)}`;
+  };
+  const restoreIssues = (issues) => issues.map(
+    (issue) => isPlainObject(issue) && typeof issue.pointer === "string" ? { ...issue, pointer: restorePath(issue.pointer, true) } : issue
+  );
+  const restoreField = (error) => {
+    if (!isPlainObject(error)) return error;
+    return {
+      ...error,
+      ...typeof error.field === "string" && { field: restorePath(error.field) },
+      ...Array.isArray(error.issues) && { issues: restoreIssues(error.issues) },
+      ...isPlainObject(error.details) && Array.isArray(error.details.issues) && {
+        details: { ...error.details, issues: restoreIssues(error.details.issues) }
+      }
+    };
+  };
+  return {
+    ...row,
+    ...Array.isArray(row.errors) && { errors: row.errors.map(restoreField) },
+    ...isPlainObject(row.adcp_error) && { adcp_error: restoreField(row.adcp_error) }
+  };
+}
+function restoreSyncAccountEnvelopeErrorIndices(response, acceptedIndices) {
+  const body = response.structuredContent;
+  if (body === void 0 || !(Array.isArray(body.errors) || isPlainObject(body.adcp_error))) return response;
+  const restored = cloneFormattedResponse(response);
+  const mirrorsStructuredContent = contentTextMirrorsStructuredContent(restored, body);
+  restored.structuredContent = restoreSyncAccountErrorIndices(body, acceptedIndices);
+  syncContentJsonText(restored, restored.structuredContent, mirrorsStructuredContent);
+  return restored;
+}
 function validateFrameworkPayload(toolName, direction, payload, version, proposalCapabilities) {
   if (toolName === "sync_reporting_status" && direction === "request") {
     return (0, import_sync_reporting_status_envelope.validateSyncReportingStatusEnvelope)(payload, version);
@@ -1780,6 +1874,7 @@ function createAdcpServer(config) {
     defaultAdcpVersion: configuredDefaultAdcpVersion,
     mcpToolProfile = "auto",
     requireCompactMutationAccountScope = false,
+    strictAccountReferences = false,
     resolveAccount,
     resolveAccountFromAuth,
     resolveSessionKey,
@@ -2495,6 +2590,7 @@ function createAdcpServer(config) {
       const wrap = meta?.wrap ?? ((data, summary) => genericResponse(toolName, data, summary));
       const toolHandler = async (params, extra) => {
         const callRequestValidationMode = effectiveRequestValidationMode(extra);
+        let notificationFailureRows = /* @__PURE__ */ new Map();
         const releaseSelection = selectServedAdcpRelease(params, capConfig, adcpVersion, defaultAdcpVersion);
         let releaseError;
         let requestRelease;
@@ -2742,7 +2838,25 @@ function createAdcpServer(config) {
                 })
               );
             }
-            const issues = idempotencyDisabled && requestIsStateChanging ? outcome.issues.filter((i) => !(i.keyword === "required" && i.pointer === "/idempotency_key")) : outcome.issues;
+            let issues = idempotencyDisabled && requestIsStateChanging ? outcome.issues.filter((i) => !(i.keyword === "required" && i.pointer === "/idempotency_key")) : outcome.issues;
+            if (toolName === "sync_accounts" && effectiveFrameworkRequestValidationMode === "strict") {
+              const eventIssues = issues.filter(isAccountNotificationEventIssue);
+              if (eventIssues.length > 0 && eventIssues.length === issues.length) {
+                const failedRows = accountNotificationFailureRows(
+                  params.accounts,
+                  eventIssues,
+                  params.delete_missing === true
+                );
+                if ((0, import_schema_validator.validateResponse)(
+                  "sync_accounts",
+                  { accounts: [...failedRows.values()] },
+                  requestRelease.validationVersion
+                ).valid) {
+                  notificationFailureRows = failedRows;
+                  issues = [];
+                }
+              }
+            }
             if (issues.length > 0) {
               if (effectiveFrameworkRequestValidationMode === "strict") {
                 const payload = (0, import_schema_errors.buildAdcpValidationErrorPayload)(toolName, "request", issues, {
@@ -2761,13 +2875,24 @@ function createAdcpServer(config) {
             }
           }
         }
-        if (hasAccount && params.account != null && resolveAccount) {
+        let unresolvedAccountPassThrough = false;
+        const suppliedAccountRef = hasAccount && params.account != null && !(strictAccountReferences && toolName === "list_accounts");
+        if (suppliedAccountRef && toolName === "list_accounts") {
+          (0, import_account_reference_warnings.warnAccountReferenceDeprecation)(
+            logger,
+            "ADCP_LIST_ACCOUNTS_FILTER_RESOLVED",
+            "[adcp/createAdcpServer] DEPRECATED: list_accounts.account is resolved as the request account (SDK 14.0 behavior). The next major release, or strictAccountReferences: true, treats it as a filter: resolveAccount is not called for it and ctx.account comes from resolveAccountFromAuth.",
+            { tool: toolName }
+          );
+        }
+        if (suppliedAccountRef && resolveAccount) {
           try {
             const account = await resolveAccount(
               params.account,
               withImmutableServedAdcpVersion(
                 {
                   toolName,
+                  provisioning: (0, import_account_provisioning.isAccountProvisioningTask)(toolName),
                   authInfo: ctx.authInfo,
                   ...ctx.agent != null && { agent: ctx.agent },
                   input: params
@@ -2800,20 +2925,32 @@ function createAdcpServer(config) {
               })
             );
           }
-        } else if (hasAccount && toolName === "list_creative_formats" && params.account != null) {
-          return finalize(
-            (0, import_errors2.adcpError)("ACCOUNT_NOT_FOUND", {
-              message: "The specified account cannot be resolved",
-              field: "account",
-              suggestion: "Omit account to use the authenticated account"
-            })
-          );
-        } else if ((!hasAccount || params.account == null) && resolveAccountFromAuth) {
+        } else if (suppliedAccountRef) {
+          if (strictAccountReferences || toolName === "list_creative_formats") {
+            return finalize(
+              (0, import_errors2.adcpError)("ACCOUNT_NOT_FOUND", {
+                message: "The specified account cannot be resolved",
+                field: "account",
+                suggestion: "The seller must configure resolveAccount to authorize supplied references; use list_accounts to discover an authorized account"
+              })
+            );
+          }
+          if (toolName !== "list_accounts") {
+            (0, import_account_reference_warnings.warnAccountReferenceDeprecation)(
+              logger,
+              "ADCP_UNRESOLVED_ACCOUNT_REFERENCE",
+              "[adcp/createAdcpServer] DEPRECATED: a request carried a buyer-supplied account reference, but no resolveAccount is configured. The reference reached the handler unverified (ctx.account is undefined). The next major release refuses it with ACCOUNT_NOT_FOUND. Configure a reference-aware resolveAccount that returns null for unknown or unauthorized references, then set strictAccountReferences: true. See https://github.com/adcontextprotocol/adcp-client/blob/main/docs/guides/account-resolution.md",
+              { tool: toolName }
+            );
+          }
+          unresolvedAccountPassThrough = true;
+        } else if (!suppliedAccountRef && resolveAccountFromAuth) {
           try {
             const account = await resolveAccountFromAuth(
               withImmutableServedAdcpVersion(
                 {
                   toolName,
+                  provisioning: (0, import_account_provisioning.isAccountProvisioningTask)(toolName),
                   authInfo: ctx.authInfo,
                   ...ctx.agent != null && { agent: ctx.agent },
                   input: params
@@ -2844,6 +2981,26 @@ function createAdcpServer(config) {
             }
           }
         }
+        if ((toolName === "get_products" || toolName === "list_products") && capConfig?.account?.requiredForProducts && ctx.account == null && // A supplied reference the compatibility pass-through handed to the
+        // handler satisfies the seller's declared requirement.
+        !unresolvedAccountPassThrough) {
+          if (!strictAccountReferences) {
+            (0, import_account_reference_warnings.warnAccountReferenceDeprecation)(
+              logger,
+              "ADCP_REQUIRED_FOR_PRODUCTS_NOT_ENFORCED",
+              `[adcp/createAdcpServer] DEPRECATED: this seller declares account.required_for_products, but ${toolName} ran without an account (SDK 14.0 behavior). The next major release, or strictAccountReferences: true, refuses it with ACCOUNT_REQUIRED.`,
+              { tool: toolName }
+            );
+          } else {
+            return finalize(
+              (0, import_errors2.adcpError)("ACCOUNT_REQUIRED", {
+                message: "This seller requires an account for product discovery",
+                field: "account",
+                suggestion: "Provision an account with sync_accounts or discover one with list_accounts"
+              })
+            );
+          }
+        }
         if (ctx.agent?.sandbox_only === true && ctx.account !== void 0 && ctx.account.sandbox !== true) {
           return finalize(
             (0, import_errors2.adcpError)("PERMISSION_DENIED", {
@@ -3105,13 +3262,23 @@ function createAdcpServer(config) {
           if (typeof claimRenewalTimer === "object" && "unref" in claimRenewalTimer) claimRenewalTimer.unref();
         }
         let mutationHandlerCompleted = false;
+        const acceptedAccountIndices = notificationFailureRows.size > 0 ? params.accounts.flatMap(
+          (_entry, index) => notificationFailureRows.has(index) ? [] : [index]
+        ) : void 0;
+        const restoreHandlerErrorIndices = (response) => acceptedAccountIndices === void 0 ? response : restoreSyncAccountEnvelopeErrorIndices(response, acceptedAccountIndices);
         try {
           if (webhookEmitter) {
             const tenantScope = webhookTenantScopeForContext(ctx);
             const scopedEmitter = tenantScope === void 0 ? configuredWebhookEmitter : webhookEmitter.forTenantScope(tenantScope);
             ctx.emitWebhook = scopedEmitter.emit.bind(scopedEmitter);
           }
-          const result = await handler(params, ctx);
+          const handlerParams = notificationFailureRows.size === 0 ? params : {
+            ...params,
+            accounts: params.accounts.filter(
+              (_entry, index) => !notificationFailureRows.has(index)
+            )
+          };
+          const result = notificationFailureRows.size > 0 && handlerParams.accounts.length === 0 ? { accounts: [], ...params.dry_run === true && { dry_run: true } } : await handler(handlerParams, ctx);
           mutationHandlerCompleted = true;
           let formatted;
           if (isFormattedResponse(result)) {
@@ -3148,6 +3315,42 @@ function createAdcpServer(config) {
           } else {
             formatted = wrap(result);
           }
+          formatted = restoreHandlerErrorIndices(formatted);
+          if (notificationFailureRows.size > 0 && !isErrorResponse(formatted) && !(Array.isArray(formatted.structuredContent?.errors) && formatted.structuredContent?.accounts === void 0)) {
+            formatted = cloneFormattedResponse(formatted);
+            const body = formatted.structuredContent;
+            const acceptedRows = Array.isArray(body.accounts) ? body.accounts.map((row) => restoreSyncAccountErrorIndices(row, acceptedAccountIndices)) : body.accounts;
+            const submitted = isSubmittedEnvelope(body);
+            let accounts;
+            if (submitted) {
+              if (acceptedRows !== void 0 && !Array.isArray(acceptedRows)) {
+                throw new Error("sync_accounts submitted accounts must be an array when present");
+              }
+              accounts = [
+                ...Array.isArray(acceptedRows) ? acceptedRows : [],
+                ...[...notificationFailureRows.entries()].sort(([a], [b]) => a - b).map(([, row]) => row)
+              ];
+            } else {
+              if (!Array.isArray(acceptedRows) || acceptedRows.length !== handlerParams.accounts.length) {
+                throw new Error("sync_accounts handler must return one result row for each accepted account entry");
+              }
+              let acceptedIndex = 0;
+              accounts = params.accounts.map(
+                (_entry, index) => notificationFailureRows.get(index) ?? acceptedRows[acceptedIndex++]
+              );
+            }
+            const merged = { ...body, accounts };
+            if (isFormattedResponse(result)) {
+              const mirrorsStructuredContent = contentTextMirrorsStructuredContent(formatted, body);
+              formatted = { ...formatted, structuredContent: wrap(merged).structuredContent };
+              syncContentJsonText(formatted, formatted.structuredContent, mirrorsStructuredContent);
+            } else {
+              const rejected = accounts.filter((row) => row.action === "failed").length;
+              const synced = accounts.length - rejected;
+              const summary = submitted ? typeof body.message === "string" ? body.message : `Task ${body.task_id} submitted` : `Synced ${synced} account${synced === 1 ? "" : "s"}`;
+              formatted = wrap(merged, `${summary}; ${rejected} account${rejected === 1 ? "" : "s"} rejected`);
+            }
+          }
           if (testControllerBridge && !isErrorResponse(formatted) && (0, import_test_controller_bridge.isSandboxRequest)(params) && ctx.account !== void 0 && !(0, import_account_mode.isSandboxOrMockAccount)(ctx.account)) {
             const resolvedAccountId = typeof ctx.account === "object" && ctx.account !== null && typeof ctx.account.account_id === "string" ? ctx.account.account_id : void 0;
             logger.debug(
@@ -3675,6 +3878,9 @@ function createAdcpServer(config) {
               });
               thrownTypedEnvelope = projectThrownAdcpError(err);
             }
+            if (thrownTypedEnvelope !== void 0) {
+              thrownTypedEnvelope = restoreHandlerErrorIndices(thrownTypedEnvelope);
+            }
             const thrownRecovery = thrownTypedEnvelope ? thrownAdcpErrorRecovery(thrownTypedEnvelope) : void 0;
             let stableTypedOutcome = !mutationHandlerCompleted && !!thrownTypedEnvelope && thrownRecovery !== "transient";
             let replayEnvelope;
@@ -3769,7 +3975,7 @@ function createAdcpServer(config) {
               message: env.message,
               stack: err instanceof Error ? err.stack : void 0
             });
-            return finalize(err);
+            return finalize(restoreHandlerErrorIndices(err));
           }
           if (err instanceof import_async_outcome.AdcpError) {
             logger.warn("Handler threw an AdcpError", {
@@ -3779,7 +3985,7 @@ function createAdcpServer(config) {
               message: err.message,
               stack: err.stack
             });
-            return finalize(projectThrownAdcpError(err));
+            return finalize(restoreHandlerErrorIndices(projectThrownAdcpError(err)));
           }
           const reason = err instanceof Error ? err.message : String(err);
           logger.error("Handler failed", {
@@ -4082,6 +4288,11 @@ function createAdcpServer(config) {
     }
   }
   checkCoherence(registeredToolNames, logger);
+  if (!resolveAccount && process.env.NODE_ENV !== "production" && ["get_products", "get_signals", "request_proposals", "create_media_buy"].some((tool) => registeredToolNames.has(tool))) {
+    logger.warn(
+      strictAccountReferences ? "Account-carrying tools are registered without resolveAccount. Supplied references will fail with ACCOUNT_NOT_FOUND." : "Account-carrying tools are registered without resolveAccount. Supplied references reach handlers unverified; this is deprecated and they will fail with ACCOUNT_NOT_FOUND in the next major release. Configure a reference-aware resolveAccount and set strictAccountReferences: true."
+    );
+  }
   const registeredMutatingTools = [...registeredToolNames].filter((t) => import_idempotency.MUTATING_TASKS.has(t));
   if (registeredToolNames.has("get_creative_features") && idempotency && idempotency.ttlSeconds < 86400) {
     throw new TypeError(