@aifabrix/builder 2.45.0 → 2.46.0

package/lib/utils/agent-trust-run-display.js

@@ -0,0 +1,231 @@
+/**
+ * @fileoverview TTY display for agent metadata trust runs (plan 143).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('./logger');
+const { sectionTitle, headerKeyValue, metadata: metaGray } = require('./cli-test-layout-chalk');
+const { statusGlyph } = require('./datasource-test-run-display');
+const { trustDecisionToRowStatus } = require('../datasource/agent-trust-map');
+
+const SEP = '────────────────────────────────';
+
+/** @type {{ datasource: number, trust: number, conf: number, status: number, cache: number }} */
+const TRUST_TABLE_COLS = {
+  datasource: 30,
+  trust: 24,
+  conf: 6,
+  status: 8,
+  cache: 8
+};
+
+function trustGlyph(trustDecision) {
+  return statusGlyph(trustDecisionToRowStatus(trustDecision));
+}
+
+function publishGateLine(trustDecision, strict) {
+  if (trustDecision === 'notTrusted') return chalk.red('blocked (trustDecision notTrusted)');
+  if (strict) {
+    return trustDecision === 'trusted'
+      ? chalk.green('allowed (strict: trusted)')
+      : chalk.yellow('blocked (strict requires trusted)');
+  }
+  return chalk.green('allowed (warning-only); use --strict to require trusted');
+}
+
+function logTrustHeader(run, env) {
+  logger.log(SEP);
+  logger.log(sectionTitle(`Semantic trust — ${run.datasourceKey}`));
+  logger.log(headerKeyValue('Environment:', env));
+  logger.log(headerKeyValue('System:', run.systemKey || '—'));
+  logger.log(SEP);
+  logger.log(metaGray('  Layer checked: business metadata (404.5 agent validation)'));
+  logger.log(metaGray('  Not checked here: vendor connectivity, sync, record counts (use test-e2e)'));
+  logger.log('');
+}
+
+function logTrustSummaryBlock(run) {
+  const confPct = Math.round((run.confidence || 0) * 100);
+  logger.log(
+    headerKeyValue(
+      'Trust:',
+      `${trustGlyph(run.trustDecision)} ${run.trustDecision} · confidence ${confPct}% · ${run.validationStatus}`
+    )
+  );
+  if (!run.validatedAt) return;
+  const hashShort = run.inputHash ? `${String(run.inputHash).slice(0, 8)}…` : '—';
+  logger.log(
+    metaGray(
+      `  Validated: ${run.validatedAt} · inputHash ${hashShort} · cache: ${run.cacheHit ? 'hit' : 'miss'}`
+    )
+  );
+}
+
+function logTrustWarningsAndFindings(run, opts) {
+  if (run.summary) {
+    logger.log('');
+    logger.log(chalk.white('  Summary'));
+    logger.log(`  ${run.summary}`);
+  }
+  const warnings = Array.isArray(run.highLevelWarnings) ? run.highLevelWarnings : [];
+  const findings = Array.isArray(run.findings) ? run.findings : [];
+  const showVerboseFindings = opts.verbose === true && findings.length > 0;
+  if (warnings.length && !showVerboseFindings) {
+    logger.log('');
+    logger.log(chalk.yellow('  Warnings (high level)'));
+    warnings.forEach(w => logger.log(`  • ${w}`));
+  }
+  if (!showVerboseFindings) return;
+  logger.log('');
+  logger.log(chalk.white('  Findings (verbose, max 10)'));
+  findings.slice(0, 10).forEach(f => {
+    logger.log(`  • [${f.severity || 'info'}] ${f.code || 'FINDING'}: ${f.message || ''}`);
+  });
+}
+
+function logTrustFooter(run, opts) {
+  logger.log('');
+  logger.log(metaGray('  ── Integration reality (informative) ──'));
+  logger.log(metaGray(`  Local manifest:  ${opts.noSync ? 'not uploaded (--no-sync)' : 'uploaded before run'}`));
+  logger.log(metaGray(`  Publish gate:    ${publishGateLine(run.trustDecision, opts.strict === true)}`));
+  logger.log(SEP);
+}
+
+function displayAgentTrustRunTTY(run, opts = {}) {
+  if (!run || opts.json === true) return;
+  const env = opts.environment ? String(opts.environment) : 'dev';
+  logTrustHeader(run, env);
+  logTrustSummaryBlock(run);
+  logTrustWarningsAndFindings(run, opts);
+  logTrustFooter(run, opts);
+}
+
+function trustCacheLabel(trustRun) {
+  if (!trustRun || typeof trustRun !== 'object') return '—';
+  if (trustRun.readLatest === true) return 'latest';
+  if (trustRun.cacheHit === true) return 'hit';
+  if (trustRun.cacheHit === false) return 'miss';
+  return '—';
+}
+
+/**
+ * @param {boolean} showCache
+ * @returns {number}
+ */
+function trustTableLineWidth(showCache) {
+  const { datasource, trust, conf, status, cache } = TRUST_TABLE_COLS;
+  let w = 2 + datasource + 1 + trust + 1 + conf + 1 + status;
+  if (showCache) w += 1 + cache;
+  return w;
+}
+
+/**
+ * @param {string} key
+ * @returns {string}
+ */
+function formatTrustTableDatasourceCol(key) {
+  return String(key || '').padEnd(TRUST_TABLE_COLS.datasource).slice(0, TRUST_TABLE_COLS.datasource);
+}
+
+/**
+ * @param {Object|null|undefined} tr
+ * @returns {string}
+ */
+function formatTrustTableTrustCol(tr) {
+  const w = TRUST_TABLE_COLS.trust;
+  if (!tr || !tr.trustDecision) return '—'.padEnd(w);
+  const decision = String(tr.trustDecision);
+  const cell = `${trustGlyph(decision)} ${decision}`;
+  return cell.length > w ? cell.slice(0, w) : cell.padEnd(w);
+}
+
+/**
+ * @param {Object|null|undefined} tr
+ * @returns {string}
+ */
+function formatTrustTableConfCol(tr) {
+  const w = TRUST_TABLE_COLS.conf;
+  if (!tr || typeof tr.confidence !== 'number') return '—'.padStart(w);
+  return `${Math.round(tr.confidence * 100)}%`.padStart(w);
+}
+
+/**
+ * @param {Object|null|undefined} tr
+ * @param {Object} row
+ * @returns {string}
+ */
+function formatTrustTableStatusCol(tr, row) {
+  const w = TRUST_TABLE_COLS.status;
+  const raw = tr ? String(tr.validationStatus || '—') : row.error || 'fail';
+  return raw.padEnd(w).slice(0, w);
+}
+
+/**
+ * @param {boolean} showCache
+ */
+function logSystemTrustTableHeader(showCache) {
+  const { datasource, trust, conf, status, cache } = TRUST_TABLE_COLS;
+  let header = `  ${'Datasource'.padEnd(datasource)} ${'Trust'.padEnd(trust)} ${'Conf.'.padStart(conf)} ${'Status'.padEnd(status)}`;
+  if (showCache) header += ` ${'Cache'.padEnd(cache)}`;
+  logger.log(chalk.white(header));
+  logger.log(chalk.gray(`  ${'─'.repeat(trustTableLineWidth(showCache))}`));
+}
+
+/**
+ * @param {Object} row
+ * @param {boolean} showCache
+ * @returns {string}
+ */
+function formatTrustTableRow(row, showCache) {
+  const tr = row.trustRun;
+  let line = `  ${formatTrustTableDatasourceCol(row.key)} ${formatTrustTableTrustCol(tr)} ${formatTrustTableConfCol(tr)} ${formatTrustTableStatusCol(tr, row)}`;
+  if (showCache) {
+    line += ` ${trustCacheLabel(tr).padEnd(TRUST_TABLE_COLS.cache).slice(0, TRUST_TABLE_COLS.cache)}`;
+  }
+  return line;
+}
+
+function logSystemTrustTable(list, opts = {}) {
+  const showCache = opts.showCache === true;
+  logSystemTrustTableHeader(showCache);
+  for (const row of list) {
+    logger.log(formatTrustTableRow(row, showCache));
+  }
+}
+
+function displaySystemTrustRollupTTY(systemKey, rows, opts = {}) {
+  if (opts.json === true) return;
+  const list = Array.isArray(rows) ? rows : [];
+  logger.log(SEP);
+  logger.log(sectionTitle(`Semantic trust — system ${systemKey} (${list.length} datasources)`));
+  const { deriveSystemStatus } = require('./external-system-system-test-tty');
+  const worst = deriveSystemStatus(
+    list.map(r => ({
+      success: r.success !== false,
+      datasourceTestRun: {
+        status: r.trustRun ? trustDecisionToRowStatus(r.trustRun.trustDecision) : 'fail'
+      }
+    }))
+  );
+  logger.log(
+    headerKeyValue('System trust:', `${statusGlyph(worst)} ${worst} (worst-of rollup)`)
+  );
+  logger.log('');
+  logSystemTrustTable(list, opts);
+  logger.log('');
+  logger.log(metaGray('  ── What this run proved ──'));
+  logger.log(metaGray(`  ✔ Semantic metadata reviewed for ${list.length} datasource(s) on dataplane`));
+  logger.log(metaGray('  ✖ Did not call external APIs or run CIP (not E2E)'));
+  logger.log(SEP);
+}
+
+module.exports = {
+  displayAgentTrustRunTTY,
+  displaySystemTrustRollupTTY,
+  formatTrustTableRow,
+  TRUST_TABLE_COLS
+};

package/lib/utils/agent-trust-run-exit.js

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview Exit codes for agent metadata trust CLI runs (plan 143).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { trustDecisionToRowStatus } = require('../datasource/agent-trust-map');
+const { deriveSystemStatus } = require('./external-system-system-test-tty');
+const { computeExitCodeFromDatasourceTestRun } = require('./datasource-test-run-exit');
+
+/**
+ * @param {Object|null|undefined} run
+ * @param {Object} [opts]
+ * @param {boolean} [opts.warningsAsErrors]
+ * @param {boolean} [opts.strict]
+ * @returns {number}
+ */
+function computeExitCodeFromTrustRun(run, opts = {}) {
+  if (!run || typeof run !== 'object') return 3;
+  const td = run.trustDecision;
+  if (run.validationStatus === 'failed' || td === 'notTrusted') return 1;
+  if (opts.strict === true && td !== 'trusted') return 1;
+  if (opts.warningsAsErrors === true && td === 'usableWithWarnings') return 1;
+  if (td === 'trusted' || td === 'usableWithWarnings' || td === 'pending') return 0;
+  return 3;
+}
+
+/**
+ * @param {Array<{ success?: boolean, trustRun?: Object|null }>} rows
+ * @param {Object} [opts]
+ * @returns {number}
+ */
+function computeSystemExitCodeFromTrustRows(rows, opts = {}) {
+  const list = Array.isArray(rows) ? rows : [];
+  let worst = 0;
+  for (const row of list) {
+    const code = computeExitCodeFromTrustRun(row && row.trustRun, opts);
+    if (code === 3) return 3;
+    if (code > worst) worst = code;
+  }
+  if (worst > 0) return worst;
+  const synthetic = list.map(r => {
+    const tr = r && r.trustRun;
+    const st = tr ? trustDecisionToRowStatus(tr.trustDecision) : 'fail';
+    return { success: st !== 'fail', datasourceTestRun: { status: st } };
+  });
+  const rollup = deriveSystemStatus(synthetic);
+  return computeExitCodeFromDatasourceTestRun(
+    { status: rollup },
+    { warningsAsErrors: opts.warningsAsErrors === true }
+  );
+}
+
+module.exports = {
+  computeExitCodeFromTrustRun,
+  computeSystemExitCodeFromTrustRows
+};

package/lib/utils/agent-trust-wait-ui.js

@@ -0,0 +1,94 @@
+/**
+ * TTY ora spinner for slow agent metadata validation POST (non-cached path).
+ *
+ * @fileoverview Agent trust wait presentation (aligned with validation-poll-ui)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('./logger');
+
+function shouldUseAgentTrustWaitSpinner() {
+  return Boolean(process && process.stdout && process.stdout.isTTY);
+}
+
+/**
+ * @param {string} [datasourceKey]
+ * @param {number} deadlineMs
+ * @returns {string}
+ */
+function buildAgentTrustWaitSpinnerText(datasourceKey, deadlineMs) {
+  const remainingSec = Math.max(0, Math.ceil((deadlineMs - Date.now()) / 1000));
+  const key =
+    datasourceKey && String(datasourceKey).trim() ? String(datasourceKey).trim() : 'datasource';
+  return `Waiting for semantic trust validation… ${key} (~${remainingSec}s left)`;
+}
+
+/**
+ * Run a blocking validate POST behind a TTY spinner (skipped when not a TTY).
+ *
+ * @async
+ * @param {Function} work - Zero-arg async function performing the HTTP call
+ * @param {Object} opts
+ * @param {string} [opts.datasourceKey]
+ * @param {number} opts.timeoutMs
+ * @returns {Promise<*>}
+ */
+async function runWithAgentTrustWaitSpinner(work, opts = {}) {
+  const timeoutMs =
+    Number.isFinite(opts.timeoutMs) && opts.timeoutMs > 0 ? opts.timeoutMs : 120000;
+  const deadlineMs = Date.now() + timeoutMs;
+  const datasourceKey = opts.datasourceKey;
+
+  if (!shouldUseAgentTrustWaitSpinner()) {
+    return work();
+  }
+
+  const ora = require('ora');
+  const spinner = ora({
+    text: buildAgentTrustWaitSpinnerText(datasourceKey, deadlineMs),
+    spinner: 'dots'
+  }).start();
+
+  const tick = setInterval(() => {
+    spinner.text = buildAgentTrustWaitSpinnerText(datasourceKey, deadlineMs);
+  }, 1000);
+
+  try {
+    return await work();
+  } finally {
+    clearInterval(tick);
+    spinner.stop();
+  }
+}
+
+const NON_TTY_LOG_MS = 5000;
+
+/**
+ * Optional one-line hint on non-TTY before a slow validate (throttled by caller usage).
+ *
+ * @param {string} [datasourceKey]
+ * @param {number} timeoutMs
+ */
+function logAgentTrustWaitHintOnce(datasourceKey, timeoutMs) {
+  if (shouldUseAgentTrustWaitSpinner()) return;
+  const budgetSec = Math.max(1, Math.ceil(timeoutMs / 1000));
+  const key =
+    datasourceKey && String(datasourceKey).trim() ? String(datasourceKey).trim() : 'datasource';
+  logger.log(
+    chalk.gray(
+      `Waiting for semantic trust validation… ${key} (may take up to ~${budgetSec}s; not cached)`
+    )
+  );
+}
+
+module.exports = {
+  shouldUseAgentTrustWaitSpinner,
+  buildAgentTrustWaitSpinnerText,
+  runWithAgentTrustWaitSpinner,
+  logAgentTrustWaitHintOnce,
+  NON_TTY_LOG_MS
+};

package/lib/utils/aifabrix-test-runtime-guard.js

@@ -0,0 +1,125 @@
+/**
+ * Refuse writes to live ~/.aifabrix paths during Jest runs.
+ *
+ * @fileoverview Test-runtime write guard for secrets and admin-secrets files
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const ALLOW_ENV = 'ALLOW_AIFABRIX_TEST_WRITE_REAL_CONFIG';
+
+/**
+ * @returns {boolean}
+ */
+function isJestTestProcess() {
+  return Boolean(process.env.JEST_WORKER_ID) || process.env.NODE_ENV === 'test';
+}
+
+/** Legacy mock Fabrix dir used across unit tests (not the operator tree when homedir differs). */
+const JEST_MOCK_FABRIX_ROOT = path.join('/home', 'test', '.aifabrix');
+
+/** Additional protected trees in cloud / monorepo dev (see plan 185 Phase 2.5). */
+const EXTRA_PROTECTED_FABRIX_ROOTS = ['/workspace/.aifabrix'];
+
+/**
+ * Resolve symlinks so `~/.aifabrix` → `/workspace/.aifabrix` matches both paths.
+ * @param {string} p
+ * @returns {string}
+ */
+function resolveFabrixPathKey(p) {
+  const resolved = path.resolve(p);
+  try {
+    if (fs.existsSync(resolved)) {
+      return fs.realpathSync(resolved);
+    }
+  } catch {
+    // ignore
+  }
+  return resolved;
+}
+
+/**
+ * @returns {string[]} Absolute live config directory paths (deduped by realpath).
+ */
+function getLiveFabrixConfigDirCandidates() {
+  const keys = new Set();
+  const dirs = [];
+  const add = (dir) => {
+    if (!dir || typeof dir !== 'string') return;
+    const key = resolveFabrixPathKey(dir);
+    if (keys.has(key)) return;
+    keys.add(key);
+    dirs.push(key);
+  };
+  add(path.join(path.resolve(os.homedir()), '.aifabrix'));
+  for (const root of EXTRA_PROTECTED_FABRIX_ROOTS) {
+    add(root);
+  }
+  return dirs;
+}
+
+/**
+ * True when the path is the operator's live ~/.aifabrix tree (not the legacy /home/test mock).
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function isLiveFabrixConfigPath(filePath) {
+  if (!filePath || typeof filePath !== 'string') return false;
+  const normalized = resolveFabrixPathKey(filePath);
+  if (
+    normalized === JEST_MOCK_FABRIX_ROOT ||
+    normalized.startsWith(`${JEST_MOCK_FABRIX_ROOT}${path.sep}`)
+  ) {
+    return false;
+  }
+  for (const liveRoot of getLiveFabrixConfigDirCandidates()) {
+    if (normalized === liveRoot || normalized.startsWith(`${liveRoot}${path.sep}`)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * During Jest, writes are allowed everywhere except the live ~/.aifabrix tree.
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+function isAllowedTestWritePath(filePath) {
+  if (!filePath || typeof filePath !== 'string') return true;
+  if (process.env[ALLOW_ENV] === '1' || process.env[ALLOW_ENV] === 'true') {
+    return true;
+  }
+  if (!isJestTestProcess()) return true;
+  return !isLiveFabrixConfigPath(filePath);
+}
+
+/**
+ * @param {string} filePath
+ * @throws {Error} When Jest would write outside sandbox
+ */
+function assertWritableSecretsPathForTests(filePath) {
+  if (!isJestTestProcess()) return;
+  if (isAllowedTestWritePath(filePath)) return;
+  throw new Error(
+    `Refusing to write secrets to live config path during tests: ${filePath}. ` +
+      'Use the Jest sandbox (default) or set ALLOW_AIFABRIX_TEST_WRITE_REAL_CONFIG=1.'
+  );
+}
+
+module.exports = {
+  ALLOW_ENV,
+  EXTRA_PROTECTED_FABRIX_ROOTS,
+  isJestTestProcess,
+  resolveFabrixPathKey,
+  getLiveFabrixConfigDirCandidates,
+  isLiveFabrixConfigPath,
+  isAllowedTestWritePath,
+  assertWritableSecretsPathForTests
+};

package/lib/utils/api.js

@@ -10,7 +10,8 @@
  * @version 2.0.0
  */
 
-const { parseErrorResponse } = require('./api-error-handler');
+const { parseErrorResponse, formatNetworkError } = require('./api-error-handler');
+const { inferServiceLabelFromUrl } = require('./service-url-label');
 const auditLogger = require('../core/audit-logger');
 
 /** Default timeout for HTTP requests (ms). Prevents hanging when the controller is unreachable. 30s allows Azure Web App cold start to complete. */
@@ -172,7 +173,7 @@ async function handleSuccessResponse(response, url, options, duration) {
  * @throws {Error} If URL is empty, null, undefined, whitespace-only, or malformed
  */
 function validateUrl(url, urlType = 'URL') {
-  if (!url || typeof url !== 'string') {
+  if (url === null || url === undefined || typeof url !== 'string') {
     throw new Error(`${urlType} is required and must be a string (received: ${JSON.stringify(url)})`);
   }
   const trimmedUrl = url.trim();
@@ -248,20 +249,18 @@ async function handleNetworkError(error, url, options, duration) {
   const flat = flattenNetworkErrorDetail(error);
   const errorMessage = withUrlContextForNetworkError(flat || error.message, url);
 
-  const parsedError = parseErrorResponse(errorMessage, 0, true);
-
-  // Extract controller URL from full URL for error data
-  let controllerUrl = null;
+  let serviceBaseUrl = null;
   const endpointUrl = url;
   if (url && typeof url === 'string' && url.trim()) {
     try {
       const urlObj = new URL(url);
-      controllerUrl = `${urlObj.protocol}//${urlObj.host}`;
+      serviceBaseUrl = `${urlObj.protocol}//${urlObj.host}`;
     } catch {
-      // If URL parsing fails, use the full URL as endpoint
-      controllerUrl = null;
+      serviceBaseUrl = null;
     }
   }
+  const serviceLabel = inferServiceLabelFromUrl(endpointUrl);
+  const parsedError = parseErrorResponse(errorMessage, 0, true);
 
   await logApiPerformance({
     url,
@@ -276,24 +275,61 @@ async function handleNetworkError(error, url, options, duration) {
     }
   });
 
-  // Include both controller URL and full endpoint URL in error data
   const errorData = {
-    ...parsedError.data,
-    controllerUrl: controllerUrl,
-    endpointUrl: endpointUrl
+    controllerUrl: serviceBaseUrl,
+    endpointUrl: endpointUrl,
+    serviceLabel
   };
+  const formattedError = formatNetworkError(errorMessage, errorData);
 
   return {
     success: false,
-    error: parsedError.message,
+    error: errorMessage,
     errorData: errorData,
-    errorType: parsedError.type,
-    formattedError: parsedError.formatted,
+    errorType: 'network',
+    formattedError,
     network: true,
     originalError: error
   };
 }
 
+/**
+ * @param {Object} options - Fetch options passed to makeApiCall
+ * @returns {{ fetchOptions: Object, singleRequestTimeoutMs: number }}
+ */
+function prepareFetchOptionsForRequest(options) {
+  const fetchOptions = { ...options };
+  const singleRequestTimeoutMs = resolveSingleRequestTimeoutMs(fetchOptions);
+  if (!fetchOptions.signal) {
+    fetchOptions.signal = AbortSignal.timeout(singleRequestTimeoutMs);
+  }
+  delete fetchOptions.timeoutMs;
+  delete fetchOptions.requestTimeoutMs;
+  return { fetchOptions, singleRequestTimeoutMs };
+}
+
+/**
+ * @param {Error} err
+ * @param {string} url
+ * @param {number} singleRequestTimeoutMs
+ * @returns {Error}
+ */
+function normalizeFetchNetworkError(err, url, singleRequestTimeoutMs) {
+  if (err?.name !== 'AbortError') {
+    return err;
+  }
+  const serviceLabel = inferServiceLabelFromUrl(url);
+  const serviceName =
+    serviceLabel === 'dataplane'
+      ? 'dataplane'
+      : serviceLabel === 'controller'
+        ? 'controller'
+        : 'service';
+  return new Error(
+    `Request timed out after ${Math.round(singleRequestTimeoutMs / 1000)} seconds. The ${serviceName} may be unreachable. Check the URL and network.`
+  );
+}
+
 /**
  * Make an API call with proper error handling
  * Uses a 30s timeout by default. Pass ``options.timeoutMs`` or ``options.requestTimeoutMs`` for
@@ -304,22 +340,14 @@ async function handleNetworkError(error, url, options, duration) {
  * @returns {Promise<Object>} Response object with success flag
  */
 async function makeApiCall(url, options = {}) {
-  // Validate URL before attempting request
   try {
     validateUrl(url, 'API endpoint URL');
   } catch (error) {
-    const duration = 0;
-    return await handleNetworkError(error, url || '', options, duration);
+    return await handleNetworkError(error, url || '', options, 0);
   }
 
   const startTime = Date.now();
-  const fetchOptions = { ...options };
-  const singleRequestTimeoutMs = resolveSingleRequestTimeoutMs(fetchOptions);
-  if (!fetchOptions.signal) {
-    fetchOptions.signal = AbortSignal.timeout(singleRequestTimeoutMs);
-  }
-  delete fetchOptions.timeoutMs;
-  delete fetchOptions.requestTimeoutMs;
+  const { fetchOptions, singleRequestTimeoutMs } = prepareFetchOptionsForRequest(options);
 
   try {
     const response = await fetch(url, fetchOptions);
@@ -332,11 +360,7 @@ async function makeApiCall(url, options = {}) {
     return await handleSuccessResponse(response, url, options, duration);
   } catch (err) {
     const duration = Date.now() - startTime;
-    const error = err?.name === 'AbortError'
-      ? new Error(
-        `Request timed out after ${Math.round(singleRequestTimeoutMs / 1000)} seconds. The controller may be unreachable. Check the URL and network.`
-      )
-      : err;
+    const error = normalizeFetchNetworkError(err, url, singleRequestTimeoutMs);
     return await handleNetworkError(error, url, options, duration);
   }
 }