@aifabrix/builder 2.45.0 → 2.46.0

package/lib/api/agent-metadata-validation.api.js

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview Agent metadata validation API (dataplane 404.5)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+const { createDataplaneApiClient } = require('./index');
+
+/**
+ * Run agent metadata validation for a datasource.
+ * POST /api/v1/external/{sourceIdOrKey}/agent-metadata-validation
+ * @requiresPermission {Dataplane} external-data-source:update
+ * @async
+ * @function runAgentMetadataValidation
+ * @param {string} dataplaneUrl - Dataplane base URL
+ * @param {string} sourceIdOrKey - Datasource key or ID
+ * @param {Object} authConfig - Authentication configuration
+ * @param {import('./types/agent-metadata-validation.types').AgentMetadataValidationRunRequest} [body]
+ * @returns {Promise<import('./types/agent-metadata-validation.types').AgentMetadataValidationRunResponse>}
+ */
+async function runAgentMetadataValidation(
+  dataplaneUrl,
+  sourceIdOrKey,
+  authConfig,
+  body = {},
+  opts = {}
+) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const requestOpts = { body };
+  if (opts.timeoutMs !== undefined && opts.timeoutMs !== null) {
+    requestOpts.timeoutMs = opts.timeoutMs;
+  }
+  return await client.post(
+    `/api/v1/external/${encodeURIComponent(sourceIdOrKey)}/agent-metadata-validation`,
+    requestOpts
+  );
+}
+
+/**
+ * Get latest agent metadata validation result.
+ * GET /api/v1/external/{sourceIdOrKey}/agent-validation
+ * @requiresPermission {Dataplane} external-data-source:read
+ * @async
+ * @function getLatestAgentMetadataValidation
+ * @param {string} dataplaneUrl - Dataplane base URL
+ * @param {string} sourceIdOrKey - Datasource key or ID
+ * @param {Object} authConfig - Authentication configuration
+ * @returns {Promise<import('./types/agent-metadata-validation.types').AgentMetadataValidationResult>}
+ */
+async function getLatestAgentMetadataValidation(
+  dataplaneUrl,
+  sourceIdOrKey,
+  authConfig,
+  opts = {}
+) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const requestOpts = {};
+  if (opts.timeoutMs !== undefined && opts.timeoutMs !== null) {
+    requestOpts.timeoutMs = opts.timeoutMs;
+  }
+  return await client.get(
+    `/api/v1/external/${encodeURIComponent(sourceIdOrKey)}/agent-validation`,
+    requestOpts
+  );
+}
+
+/**
+ * List agent metadata validation history.
+ * GET /api/v1/external/{sourceIdOrKey}/agent-validation/history
+ * @requiresPermission {Dataplane} external-data-source:read
+ * @async
+ * @function listAgentMetadataValidationHistory
+ * @param {string} dataplaneUrl - Dataplane base URL
+ * @param {string} sourceIdOrKey - Datasource key or ID
+ * @param {Object} authConfig - Authentication configuration
+ * @returns {Promise<import('./types/agent-metadata-validation.types').AgentMetadataValidationHistoryItem[]>}
+ */
+async function listAgentMetadataValidationHistory(
+  dataplaneUrl,
+  sourceIdOrKey,
+  authConfig
+) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  return await client.get(
+    `/api/v1/external/${encodeURIComponent(sourceIdOrKey)}/agent-validation/history`
+  );
+}
+
+module.exports = {
+  runAgentMetadataValidation,
+  getLatestAgentMetadataValidation,
+  listAgentMetadataValidationHistory
+};

package/lib/api/api-response-errors.js

@@ -0,0 +1,124 @@
+/**
+ * Throw CLI errors from ApiClient responses with formatted output preserved.
+ *
+ * @fileoverview Dataplane/controller API failure helpers
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { formatApiError } = require('../utils/api-error-handler');
+const {
+  enrichUnresolvableGovernanceSubjectsError
+} = require('../governance/governance-cli-errors');
+const { inferServiceLabelFromUrl } = require('../utils/service-url-label');
+
+/**
+ * @param {Object|undefined} res - ApiClient response
+ * @param {string} fallbackMessage
+ * @returns {string}
+ */
+function resolveApiErrorMessage(res, fallbackMessage) {
+  if (!res) {
+    return fallbackMessage;
+  }
+  const fromError =
+    res.error &&
+    (res.error.formattedError || res.error.error || res.error.message);
+  return (
+    res.formattedError ||
+    fromError ||
+    (typeof res.error === 'string' ? res.error : null) ||
+    fallbackMessage
+  );
+}
+
+/**
+ * @param {Object|undefined} res
+ * @param {string} endpointUrl
+ * @returns {{ endpoint: string, serviceLabel: string }}
+ */
+function resolveApiFailureEndpointContext(res, endpointUrl) {
+  const endpoint =
+    (res && res.errorData && res.errorData.endpointUrl) || endpointUrl || '';
+  const serviceLabel =
+    (res && res.errorData && res.errorData.serviceLabel) ||
+    inferServiceLabelFromUrl(endpoint);
+  return { endpoint, serviceLabel };
+}
+
+/**
+ * @param {Object|undefined} res
+ * @param {string} endpoint
+ * @param {string} serviceLabel
+ * @returns {Object}
+ */
+function buildEnrichedApiFailureResponse(res, endpoint, serviceLabel) {
+  return {
+    ...res,
+    errorData: {
+      ...(res && res.errorData),
+      endpointUrl: endpoint,
+      serviceLabel
+    }
+  };
+}
+
+/**
+ * @param {Error} err
+ * @param {Object|undefined} res
+ * @param {string} endpoint
+ * @param {string} serviceLabel
+ * @param {Object} enriched
+ */
+function assignApiFailureErrorFields(err, res, endpoint, serviceLabel, enriched) {
+  err.formatted =
+    res && res.formattedError ? res.formattedError : formatApiError(enriched, null);
+  err.network = Boolean(res && res.network === true);
+  err.status = res && typeof res.status === 'number' ? res.status : 0;
+  err.endpointUrl = endpoint;
+  err.serviceLabel = serviceLabel;
+}
+
+/**
+ * @param {Object|undefined} res
+ * @param {string} endpointUrl
+ * @returns {Error}
+ */
+function buildApiFailureError(res, endpointUrl, context = {}) {
+  const message = resolveApiErrorMessage(res, 'Request failed');
+  const err = new Error(message);
+  const { endpoint, serviceLabel } = resolveApiFailureEndpointContext(res, endpointUrl);
+  const enriched = buildEnrichedApiFailureResponse(res, endpoint, serviceLabel);
+  assignApiFailureErrorFields(err, res, endpoint, serviceLabel, enriched);
+  if (
+    typeof endpoint === 'string' &&
+    endpoint.includes('/governance-scenarios/generate')
+  ) {
+    enrichUnresolvableGovernanceSubjectsError(err, context);
+  }
+  return err;
+}
+
+/**
+ * @param {Object} res - ApiClient response (`success: false`)
+ * @param {{ fallbackMessage?: string, endpointUrl?: string }} [context]
+ * @throws {Error}
+ */
+function throwIfApiFailed(res, context = {}) {
+  if (!res || res.success !== false) {
+    return;
+  }
+  const endpointUrl =
+    context.endpointUrl ||
+    (res.errorData && res.errorData.endpointUrl) ||
+    '';
+  throw buildApiFailureError(res, endpointUrl || context.endpointUrl || '', context);
+}
+
+module.exports = {
+  throwIfApiFailed,
+  buildApiFailureError,
+  resolveApiErrorMessage
+};

package/lib/api/audit-api-helpers.js

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview Shared helpers for dataplane audit API responses
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+
+/**
+ * @param {*} res
+ * @throws {Error}
+ */
+function assertAuditApiSuccess(res) {
+  if (!res || typeof res !== 'object') {
+    throw new Error('Audit API returned an empty response');
+  }
+  if (res.success === false) {
+    const msg =
+      (res.error && (res.error.formattedError || res.error.error || res.error.message)) ||
+      res.formattedError ||
+      'Audit API request failed';
+    const err = new Error(msg);
+    if (res.status) err.status = res.status;
+    throw err;
+  }
+}
+
+/**
+ * @param {*} res
+ * @returns {{ data: Array, meta: Object|null, raw: Object|null }}
+ */
+function unwrapPaginatedAuditList(res) {
+  assertAuditApiSuccess(res);
+  const body = unwrapApiData(res);
+  if (!body || typeof body !== 'object') {
+    return { data: [], meta: null, raw: null };
+  }
+  const data = Array.isArray(body.data)
+    ? body.data
+    : Array.isArray(body.items)
+      ? body.items
+      : [];
+  const meta = body.meta && typeof body.meta === 'object' ? body.meta : null;
+  return { data, meta, raw: body };
+}
+
+/**
+ * Unwrap execution sub-resource envelope `{ root: T }`.
+ * @param {*} res
+ * @returns {*|null}
+ */
+function unwrapExecutionSubresource(res) {
+  assertAuditApiSuccess(res);
+  const body = unwrapApiData(res);
+  if (body === null || body === undefined) return null;
+  if (typeof body === 'object' && Object.prototype.hasOwnProperty.call(body, 'root')) {
+    return body.root;
+  }
+  return body;
+}
+
+module.exports = {
+  assertAuditApiSuccess,
+  unwrapPaginatedAuditList,
+  unwrapExecutionSubresource
+};

package/lib/api/audit.api.js

@@ -0,0 +1,119 @@
+/**
+ * @fileoverview Dataplane audit read API (Plan 407.1 / 407.3 evidence matrix)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { createDataplaneApiClient } = require('./index');
+const { unwrapPaginatedAuditList, unwrapExecutionSubresource } = require('./audit-api-helpers');
+
+const AUDIT_BASE = '/api/v1/audit';
+const DEFAULT_PAGE_SIZE = 100;
+
+/**
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {Object} [query]
+ * @returns {Promise<{ data: import('./types/audit.types').AuditExecutionListItem[], meta: import('./types/audit.types').AuditListMeta|null }>}
+ * @requiresPermission {Dataplane} audit:read
+ */
+async function queryExecutions(dataplaneUrl, authConfig, query = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(`${AUDIT_BASE}/executions`, {
+    params: {
+      page: 1,
+      pageSize: DEFAULT_PAGE_SIZE,
+      ...query
+    }
+  });
+  return unwrapPaginatedAuditList(res);
+}
+
+/**
+ * @requiresPermission {Dataplane} audit:read
+ */
+async function queryRbacDecisions(dataplaneUrl, authConfig, query = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(`${AUDIT_BASE}/rbac-decisions`, {
+    params: {
+      page: 1,
+      pageSize: DEFAULT_PAGE_SIZE,
+      sort: '-timestamp',
+      ...query
+    }
+  });
+  return unwrapPaginatedAuditList(res);
+}
+
+/**
+ * @requiresPermission {Dataplane} audit:read
+ */
+async function queryAbacTraces(dataplaneUrl, authConfig, query = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(`${AUDIT_BASE}/abac-traces`, {
+    params: {
+      page: 1,
+      pageSize: DEFAULT_PAGE_SIZE,
+      ...query
+    }
+  });
+  return unwrapPaginatedAuditList(res);
+}
+
+/**
+ * @requiresPermission {Dataplane} audit:read
+ */
+async function getExecutionRbac(dataplaneUrl, authConfig, executionId) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(`${AUDIT_BASE}/executions/${executionId}/rbac`);
+  return unwrapExecutionSubresource(res);
+}
+
+/**
+ * @requiresPermission {Dataplane} audit:read
+ */
+async function getExecutionAbac(dataplaneUrl, authConfig, executionId) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(`${AUDIT_BASE}/executions/${executionId}/abac`);
+  return unwrapExecutionSubresource(res);
+}
+
+/**
+ * @requiresPermission {Dataplane} audit:read
+ */
+async function getExecutionTrace(dataplaneUrl, authConfig, executionId) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(`${AUDIT_BASE}/executions/${executionId}/trace`);
+  return unwrapExecutionSubresource(res);
+}
+
+/**
+ * @requiresPermission {Dataplane} audit:read
+ */
+async function getExecutionSteps(dataplaneUrl, authConfig, executionId) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(`${AUDIT_BASE}/executions/${executionId}/steps`);
+  return unwrapExecutionSubresource(res);
+}
+
+/**
+ * @requiresPermission {Dataplane} audit:read
+ */
+async function getExecutionErrors(dataplaneUrl, authConfig, executionId) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(`${AUDIT_BASE}/executions/${executionId}/errors`);
+  return unwrapExecutionSubresource(res);
+}
+
+module.exports = {
+  queryExecutions,
+  queryRbacDecisions,
+  queryAbacTraces,
+  getExecutionRbac,
+  getExecutionAbac,
+  getExecutionTrace,
+  getExecutionSteps,
+  getExecutionErrors
+};

package/lib/api/auth-cache.api.js

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview Controller auth/RBAC cache API
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { ApiClient } = require('./index');
+
+const CLEAR_PATH = '/api/v1/auth/cache/clear';
+const INVALIDATE_PATH = '/api/v1/auth/cache/invalidate';
+
+/**
+ * Clear all controller cache entries
+ * @requiresPermission {Controller} cache:admin
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @returns {Promise<Object>}
+ */
+async function clearAuthCache(controllerUrl, authConfig) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.post(CLEAR_PATH);
+}
+
+/**
+ * Invalidate cache entries matching a pattern
+ * @requiresPermission {Controller} cache:admin
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {string} pattern
+ * @returns {Promise<Object>}
+ */
+async function invalidateAuthCache(controllerUrl, authConfig, pattern) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.post(INVALIDATE_PATH, { body: { pattern } });
+}
+
+module.exports = {
+  clearAuthCache,
+  invalidateAuthCache
+};

package/lib/api/certificates.api.js

@@ -4,7 +4,7 @@
  * @version 2.0.0
  */
 
-const { ApiClient } = require('./index');
+const { createDataplaneApiClient } = require('./index');
 const { normalizeDataplaneAuth } = require('./validation-run.api');
 
 /**
@@ -36,7 +36,7 @@ function dataplaneAuthForBearerGet(authConfig) {
  * @returns {Promise<Object>} API envelope `{ success, data?, status, ... }`
  */
 async function getActiveIntegrationCertificate(dataplaneUrl, authConfig, systemKey, datasourceKey) {
-  const client = new ApiClient(dataplaneUrl, dataplaneAuthForBearerGet(authConfig));
+  const client = createDataplaneApiClient(dataplaneUrl, dataplaneAuthForBearerGet(authConfig));
   const path = `/api/v1/systems/${encodeURIComponent(systemKey)}/datasources/${encodeURIComponent(
     datasourceKey
   )}/certificates/active`;
@@ -54,7 +54,7 @@ async function getActiveIntegrationCertificate(dataplaneUrl, authConfig, systemK
  * @returns {Promise<Object>}
  */
 async function listIntegrationCertificates(dataplaneUrl, authConfig, params = {}) {
-  const client = new ApiClient(dataplaneUrl, dataplaneAuthForBearerGet(authConfig));
+  const client = createDataplaneApiClient(dataplaneUrl, dataplaneAuthForBearerGet(authConfig));
   return await client.get('/api/v1/certificates', { params });
 }
 
@@ -69,7 +69,7 @@ async function listIntegrationCertificates(dataplaneUrl, authConfig, params = {}
  * @returns {Promise<Object>}
  */
 async function verifyIntegrationCertificate(dataplaneUrl, authConfig, body) {
-  const client = new ApiClient(dataplaneUrl, dataplaneAuthForBearerGet(authConfig));
+  const client = createDataplaneApiClient(dataplaneUrl, dataplaneAuthForBearerGet(authConfig));
   return await client.post('/api/v1/certificates/verify', { body: body || {} });
 }
 

package/lib/api/credential.api.js

@@ -4,7 +4,7 @@
  * @version 2.0.0
  */
 
-const { ApiClient } = require('./index');
+const { createDataplaneApiClient } = require('./index');
 
 const CREDENTIAL_SECRET_ENDPOINT = '/api/v1/credential/secret';
 
@@ -29,7 +29,7 @@ async function storeCredentialSecrets(dataplaneUrl, authConfig, items) {
   if (!items || !Array.isArray(items) || items.length === 0) {
     return { stored: 0 };
   }
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post(CREDENTIAL_SECRET_ENDPOINT, {
     body: items
   });

package/lib/api/dataplane-health.api.js

@@ -0,0 +1,137 @@
+/**
+ * Dataplane health (public) — read dataplane `version` and optional
+ * `minBuilderCliVersion` for the Builder CLI compatibility gate (plan 142.0).
+ *
+ * Reads `GET /api/v1/health` first (canonical, plan 403.0) and falls back to
+ * `GET /health` for older dataplanes during rollout. The endpoint is public
+ * (`security: []`); no auth header is sent.
+ *
+ * @fileoverview Read dataplane health JSON without authentication
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ * @requiresPermission none — public dataplane health endpoint (security: [])
+ */
+
+'use strict';
+
+require('./types/dataplane-health.types');
+const { ApiClient } = require('./index');
+
+const PRIMARY_ENDPOINT = '/api/v1/health';
+const FALLBACK_ENDPOINT = '/health';
+
+/**
+ * Extract the inner JSON body from the harmonized ApiClient response shape.
+ * @private
+ * @param {Object} response
+ * @returns {Object|null}
+ */
+function unwrapBody(response) {
+  if (!response || response.success === false || response.data === null || response.data === undefined) {
+    return null;
+  }
+  const outer = response.data;
+  if (!outer || typeof outer !== 'object') {
+    return null;
+  }
+  // Some dataplane shapes return `{ data: { ... } }`; the general health route
+  // returns the payload directly. Accept both.
+  const inner = outer.data !== undefined && outer.data !== null && typeof outer.data === 'object'
+    ? outer.data
+    : outer;
+  if (!inner || typeof inner !== 'object') {
+    return null;
+  }
+  return inner;
+}
+
+/**
+ * Parse a raw ApiClient response into a normalized health snapshot.
+ *
+ * @param {Object} response - ApiClient.get response (`{ success, data, ... }`)
+ * @param {string} [endpoint] - Endpoint that produced the response (recorded on snapshot)
+ * @returns {import('./types/dataplane-health.types').DataplaneHealthSnapshot|null}
+ *          Snapshot, or null when the response is not parseable
+ */
+function parseGeneralHealthResponse(response, endpoint) {
+  const body = unwrapBody(response);
+  if (!body) return null;
+
+  const status = typeof body.status === 'string' ? body.status : 'unknown';
+  const version = typeof body.version === 'string' && body.version.trim()
+    ? body.version.trim()
+    : undefined;
+
+  let minBuilderCliVersion;
+  if (typeof body.minBuilderCliVersion === 'string') {
+    const trimmed = body.minBuilderCliVersion.trim();
+    if (trimmed) minBuilderCliVersion = trimmed;
+  }
+
+  return {
+    status,
+    version,
+    minBuilderCliVersion,
+    endpoint: endpoint || null
+  };
+}
+
+/**
+ * Fetch dataplane general health (public endpoint, no auth).
+ *
+ * Tries `/api/v1/health` first; on failure falls back to `/health` (compatibility
+ * with older dataplanes that did not expose the v1 health route during rollout).
+ *
+ * @async
+ * @param {string} dataplaneUrl - Dataplane base URL (e.g. `http://localhost:3201`)
+ * @param {Object} [options]
+ * @param {number} [options.timeoutMs] - Optional timeout in milliseconds
+ * @returns {Promise<import('./types/dataplane-health.types').DataplaneHealthSnapshot|null>}
+ *          Snapshot, or null when both endpoints fail
+ * @throws {Error} When dataplaneUrl is missing or not a string
+ */
+async function fetchDataplaneGeneralHealth(dataplaneUrl, options = {}) {
+  if (!dataplaneUrl || typeof dataplaneUrl !== 'string') {
+    throw new Error('dataplaneUrl is required and must be a string');
+  }
+  const client = new ApiClient(dataplaneUrl);
+  const requestOpts = {};
+  if (options.timeoutMs !== undefined && options.timeoutMs !== null) {
+    requestOpts.timeoutMs = options.timeoutMs;
+  }
+
+  const primary = await safeGet(client, PRIMARY_ENDPOINT, requestOpts);
+  const primarySnapshot = parseGeneralHealthResponse(primary, PRIMARY_ENDPOINT);
+  if (primarySnapshot) return primarySnapshot;
+
+  const fallback = await safeGet(client, FALLBACK_ENDPOINT, requestOpts);
+  const fallbackSnapshot = parseGeneralHealthResponse(fallback, FALLBACK_ENDPOINT);
+  if (fallbackSnapshot) return fallbackSnapshot;
+
+  return null;
+}
+
+/**
+ * GET that swallows transport errors (timeouts / DNS / ECONNREFUSED) so callers
+ * can attempt a fallback endpoint without try/catch noise.
+ * @private
+ * @async
+ * @param {ApiClient} client
+ * @param {string} endpoint
+ * @param {Object} options
+ * @returns {Promise<Object|null>}
+ */
+async function safeGet(client, endpoint, options) {
+  try {
+    return await client.get(endpoint, options);
+  } catch (_error) {
+    return null;
+  }
+}
+
+module.exports = {
+  fetchDataplaneGeneralHealth,
+  parseGeneralHealthResponse,
+  PRIMARY_ENDPOINT,
+  FALLBACK_ENDPOINT
+};

package/lib/api/dataplane-sync.api.js

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Dataplane sync API (Controller)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { ApiClient } = require('./index');
+
+/**
+ * Trigger full identity sync to dataplane for an environment
+ * @requiresPermission {Controller} admin:sync
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {string} envKey
+ * @returns {Promise<Object>}
+ */
+async function fullSyncToDataplane(controllerUrl, authConfig, envKey) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.post(`/api/v1/sync/dataplane/${encodeURIComponent(envKey)}/full`);
+}
+
+module.exports = {
+  fullSyncToDataplane
+};