@aifabrix/builder 2.45.0 → 2.46.0

package/lib/api/index.js

@@ -14,13 +14,15 @@ const { makeApiCall, authenticatedApiCall } = require('../utils/api');
 class ApiClient {
   /**
    * Create an API client instance.
-   * App endpoints receive token-only auth (Bearer). x-client-id/x-client-secret are not sent to app endpoints.
+   * App endpoints receive token-only auth (Bearer). x-client-id/x-client-secret are used only for the controller token endpoint.
    * @param {string} baseUrl - Base URL for the API (controller URL)
    * @param {Object} [authConfig] - Authentication configuration
-   * @param {string} [authConfig.type] - Auth type ('bearer' | 'client-token')
+   * @param {string} [authConfig.type] - Auth type ('bearer' | 'client-token' | 'client-credentials')
    * @param {string} [authConfig.token] - Bearer token
+   * @param {string} [authConfig.clientId] - Client ID (client-credentials)
+   * @param {string} [authConfig.clientSecret] - Client secret (client-credentials)
    */
-  constructor(baseUrl, authConfig = {}) {
+  constructor(baseUrl, authConfig = {}, clientOptions = {}) {
     if (baseUrl === null || baseUrl === undefined || typeof baseUrl !== 'string') {
       throw new Error('baseUrl is required and must be a string');
     }
@@ -30,6 +32,25 @@ class ApiClient {
     }
     this.baseUrl = trimmedUrl;
     this.authConfig = authConfig;
+    const opts = clientOptions && typeof clientOptions === 'object' ? clientOptions : {};
+    this.enforceCliVersion = Boolean(opts.enforceCliVersion);
+    this.controllerUrlForGate = opts.controllerUrl || null;
+  }
+
+  /**
+   * Plan 142.0: block dataplane mutations when Builder CLI is below minimum.
+   * @private
+   * @async
+   * @returns {Promise<void>}
+   */
+  async _ensureDataplaneCliVersionGate() {
+    if (!this.enforceCliVersion) {
+      return;
+    }
+    const { assertDataplaneCliVersionCompatible } = require('../utils/dataplane-cli-version-gate');
+    await assertDataplaneCliVersionCompatible(this.baseUrl, {
+      controllerUrl: this.controllerUrlForGate
+    });
   }
 
   /**
@@ -68,6 +89,41 @@ class ApiClient {
     return headers;
   }
 
+  /**
+   * True when endpoint is the controller client-credentials token exchange.
+   * @private
+   * @param {string} endpoint - API endpoint path
+   * @returns {boolean}
+   */
+  _isClientCredentialsTokenEndpoint(endpoint) {
+    const path = endpoint.startsWith('/') ? endpoint : `/${endpoint}`;
+    return path === '/api/v1/auth/token';
+  }
+
+  /**
+   * Add x-client-id/x-client-secret only for POST /api/v1/auth/token (never for app endpoints).
+   * @private
+   * @param {string} endpoint - API endpoint path
+   * @param {Object} headers - Request headers built by _buildHeaders
+   * @returns {Object}
+   */
+  _applyClientCredentialHeadersForTokenEndpoint(endpoint, headers) {
+    if (this.authConfig.type !== 'client-credentials') {
+      return headers;
+    }
+    if (!this._isClientCredentialsTokenEndpoint(endpoint)) {
+      return headers;
+    }
+    const out = { ...headers };
+    if (this.authConfig.clientId) {
+      out['x-client-id'] = String(this.authConfig.clientId);
+    }
+    if (this.authConfig.clientSecret) {
+      out['x-client-secret'] = String(this.authConfig.clientSecret);
+    }
+    return out;
+  }
+
   /**
    * Make a GET request
    * @async
@@ -78,6 +134,7 @@ class ApiClient {
    * @returns {Promise<Object>} API response
    */
   async get(endpoint, options = {}) {
+    await this._ensureDataplaneCliVersionGate();
     let url = this._buildUrl(endpoint);
     const headers = this._buildHeaders(options.headers);
 
@@ -119,8 +176,12 @@ class ApiClient {
    * @returns {Promise<Object>} API response
    */
   async post(endpoint, options = {}) {
+    await this._ensureDataplaneCliVersionGate();
     let url = this._buildUrl(endpoint);
-    const headers = this._buildHeaders(options.headers);
+    const headers = this._applyClientCredentialHeadersForTokenEndpoint(
+      endpoint,
+      this._buildHeaders(options.headers)
+    );
 
     // Add query parameters if provided
     if (options.params) {
@@ -167,6 +228,7 @@ class ApiClient {
    * @returns {Promise<Object>} API response
    */
   async postFormData(endpoint, formData, options = {}) {
+    await this._ensureDataplaneCliVersionGate();
     const url = this._buildUrl(endpoint);
     const headers = this._buildHeaders(options.headers || {}, { skipContentType: true });
 
@@ -194,6 +256,7 @@ class ApiClient {
    * @returns {Promise<Object>} API response
    */
   async patch(endpoint, options = {}) {
+    await this._ensureDataplaneCliVersionGate();
     const url = this._buildUrl(endpoint);
     const headers = this._buildHeaders(options.headers);
 
@@ -224,6 +287,7 @@ class ApiClient {
    * @returns {Promise<Object>} API response
    */
   async put(endpoint, options = {}) {
+    await this._ensureDataplaneCliVersionGate();
     const url = this._buildUrl(endpoint);
     const headers = this._buildHeaders(options.headers);
 
@@ -253,6 +317,7 @@ class ApiClient {
    * @returns {Promise<Object>} API response
    */
   async delete(endpoint, options = {}) {
+    await this._ensureDataplaneCliVersionGate();
     const url = this._buildUrl(endpoint);
     const headers = this._buildHeaders(options.headers);
 
@@ -270,7 +335,25 @@ class ApiClient {
   }
 }
 
+/**
+ * Dataplane-scoped client — enforces Builder CLI version gate before each request.
+ * Do not use for `fetchDataplaneGeneralHealth` (health must stay ungated).
+ *
+ * @param {string} dataplaneUrl - Dataplane base URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {Object} [options]
+ * @param {string} [options.controllerUrl] - Controller URL for device cache lookup
+ * @returns {ApiClient}
+ */
+function createDataplaneApiClient(dataplaneUrl, authConfig, options = {}) {
+  return new ApiClient(dataplaneUrl, authConfig, {
+    enforceCliVersion: true,
+    controllerUrl: options.controllerUrl
+  });
+}
+
 module.exports = {
-  ApiClient
+  ApiClient,
+  createDataplaneApiClient
 };
 

package/lib/api/lifecycle.api.js

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview Dataplane Enterprise AI Certification lifecycle API client (419.0).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { createDataplaneApiClient } = require('./index');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+
+/**
+ * GET /api/v1/external/systems/{systemKey}/lifecycle
+ * @requiresPermission {Dataplane} external-system:read
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} systemKey
+ * @param {{ details?: boolean, summary?: boolean }} [opts]
+ * @returns {Promise<Object>}
+ */
+async function getSystemLifecycleReport(dataplaneUrl, authConfig, systemKey, opts = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const params = {};
+  if (opts.details === true) params.details = true;
+  if (opts.summary === true) params.summary = true;
+  const res = await client.get(`/api/v1/external/systems/${encodeURIComponent(systemKey)}/lifecycle`, {
+    params
+  });
+  if (res && res.success === false) {
+    const msg =
+      (res.error && (res.error.formattedError || res.error.error || res.error.message)) ||
+      res.formattedError ||
+      'Lifecycle report request failed';
+    throw new Error(msg);
+  }
+  const unwrapped = unwrapApiData(res);
+  if (!unwrapped || !unwrapped.systemKey) {
+    throw new Error('Lifecycle report returned an unexpected response shape');
+  }
+  return unwrapped;
+}
+
+/**
+ * POST /api/v1/external/systems/{systemKey}/lifecycle/run
+ * @requiresPermission {Dataplane} external-system:update
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} systemKey
+ * @param {Object} [body]
+ * @returns {Promise<Object>}
+ */
+async function runSystemLifecycle(dataplaneUrl, authConfig, systemKey, body = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.post(
+    `/api/v1/external/systems/${encodeURIComponent(systemKey)}/lifecycle/run`,
+    { body }
+  );
+  if (res && res.success === false) {
+    const msg =
+      (res.error && (res.error.formattedError || res.error.error || res.error.message)) ||
+      res.formattedError ||
+      'Lifecycle run request failed';
+    throw new Error(msg);
+  }
+  const unwrapped = unwrapApiData(res);
+  if (!unwrapped || !unwrapped.report) {
+    throw new Error('Lifecycle run returned an unexpected response shape');
+  }
+  return unwrapped;
+}
+
+module.exports = {
+  getSystemLifecycleReport,
+  runSystemLifecycle
+};

package/lib/api/pipeline.api.js

@@ -4,8 +4,9 @@
  * @version 2.0.0
  */
 
-const { ApiClient } = require('./index');
+const { ApiClient, createDataplaneApiClient } = require('./index');
 const { postValidationRunAndOptionalPoll } = require('./validation-runner');
+const { withStageOnValidationRunBody } = require('../utils/validation-run-stage');
 
 /**
  * @param {Object} opts
@@ -30,7 +31,7 @@ function buildValidationRunPayloadTestBody({ validationScope, systemKey, datasou
   if (validationScope === 'externalDataSource') {
     body.datasourceKey = datasourceKey;
   }
-  return body;
+  return withStageOnValidationRunBody(body, body.runType);
 }
 
 /**
@@ -127,7 +128,7 @@ async function getPipelineHealth(controllerUrl, envKey) {
  * @throws {Error} If publish fails
  */
 async function publishDatasourceViaPipeline(dataplaneUrl, systemKey, authConfig, datasourceConfig) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/pipeline/${systemKey}/upload`, {
     body: datasourceConfig
   });
@@ -147,7 +148,7 @@ async function publishDatasourceViaPipeline(dataplaneUrl, systemKey, authConfig,
  * @throws {Error} If request fails
  */
 async function validatePipelineConfig(dataplaneUrl, authConfig, { config }) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post('/api/v1/pipeline/validate', {
     body: { config }
   });
@@ -242,12 +243,13 @@ async function testDatasourceViaPipeline({ dataplaneUrl, systemKey, datasourceKe
  * @param {Object} authConfig - Authentication configuration (must include token for Bearer; client id/secret rejected)
  * @param {Object} payload - { version, application, dataSources }; optional status (default "draft")
  * @param {string} [payload.status="draft"] - "draft" or "published"; Builder uses "draft"
+ * @param {boolean} [payload.force=false] - When true, bypass guards on active datasource publish
  * @returns {Promise<Object>} API envelope `{ success, data }` where `data` is PublicationResult (uploadId, system, datasources, generateMcpContract, …)
  * @throws {Error} If upload fails
  */
 async function uploadApplicationViaPipeline(dataplaneUrl, authConfig, payload) {
   const body = { ...payload, status: payload.status ?? 'draft' };
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post('/api/v1/pipeline/upload', {
     body
   });

package/lib/api/protection.api.js

@@ -0,0 +1,157 @@
+/**
+ * @fileoverview Protection manifest API (dataplane /api/v1/protection/*).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { createDataplaneApiClient } = require('./index');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+
+const BASE = '/api/v1/protection';
+
+/**
+ * @param {*} res
+ * @returns {*}
+ */
+function unwrapBody(res) {
+  return unwrapApiData(res) ?? res;
+}
+
+/**
+ * POST /api/v1/protection/validate
+ * @requiresPermission {Dataplane} external-system:read
+ */
+async function validateProtection(dataplaneUrl, authConfig, manifest, opts = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const params = {};
+  if (opts.strict === true) params.strict = true;
+  if (opts.explain === true) params.explain = true;
+  const res = await client.post(`${BASE}/validate`, {
+    body: { manifest },
+    params
+  });
+  return unwrapBody(res);
+}
+
+/**
+ * POST /api/v1/protection/simulate
+ * @requiresPermission {Dataplane} external-system:read
+ */
+async function simulateProtection(dataplaneUrl, authConfig, manifest, opts = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const params = {};
+  if (opts.strict === true) params.strict = true;
+  if (opts.explain === true) params.explain = true;
+  if (opts.sampleSize !== undefined && opts.sampleSize !== null) {
+    params.sampleSize = opts.sampleSize;
+  }
+  const res = await client.post(`${BASE}/simulate`, {
+    body: { manifest },
+    params
+  });
+  return unwrapBody(res);
+}
+
+/**
+ * POST /api/v1/protection/upload
+ * @requiresPermission {Dataplane} external-system:publish
+ */
+async function uploadProtection(dataplaneUrl, authConfig, manifest) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.post(`${BASE}/upload`, { body: { manifest } });
+  return unwrapBody(res);
+}
+
+/**
+ * GET /api/v1/protection/{key}
+ * @requiresPermission {Dataplane} external-system:read
+ */
+async function getProtection(dataplaneUrl, authConfig, key) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(`${BASE}/${encodeURIComponent(key)}`);
+  return unwrapBody(res);
+}
+
+/**
+ * GET /api/v1/protection/{key}/status
+ * @requiresPermission {Dataplane} external-system:read
+ */
+async function getProtectionStatus(dataplaneUrl, authConfig, key) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(`${BASE}/${encodeURIComponent(key)}/status`);
+  return unwrapBody(res);
+}
+
+/**
+ * @param {*} body
+ * @returns {Object[]}
+ */
+function extractProtectionListItems(body) {
+  if (!body || typeof body !== 'object') {
+    return [];
+  }
+  if (Array.isArray(body.data)) {
+    return body.data;
+  }
+  if (Array.isArray(body.items)) {
+    return body.items;
+  }
+  if (Array.isArray(body)) {
+    return body;
+  }
+  return [];
+}
+
+/**
+ * GET /api/v1/protection
+ * @requiresPermission {Dataplane} external-system:read
+ * @returns {Promise<{ items: Object[], meta: Object|null, raw: * }>}
+ */
+async function listProtectionManifests(dataplaneUrl, authConfig, options = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(BASE, { params: options });
+  const body = unwrapBody(res);
+  return {
+    items: extractProtectionListItems(body),
+    meta: body && typeof body === 'object' && body.meta ? body.meta : null,
+    raw: body
+  };
+}
+
+/**
+ * DELETE /api/v1/protection/{key}
+ * @requiresPermission {Dataplane} external-system:delete
+ */
+async function deleteProtection(dataplaneUrl, authConfig, key) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  return await client.delete(`${BASE}/${encodeURIComponent(key)}`);
+}
+
+/**
+ * Find deployed protection key by datasource key (client-side scan).
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} datasourceKey
+ * @returns {Promise<string|null>}
+ */
+async function findProtectionKeyByDatasource(dataplaneUrl, authConfig, datasourceKey) {
+  const { items } = await listProtectionManifests(dataplaneUrl, authConfig, {
+    page: 1,
+    pageSize: 100
+  });
+  const match = items.find((row) => String(row?.datasourceKey || '').trim() === datasourceKey);
+  return match?.key ? String(match.key) : null;
+}
+
+module.exports = {
+  validateProtection,
+  simulateProtection,
+  uploadProtection,
+  getProtection,
+  getProtectionStatus,
+  listProtectionManifests,
+  deleteProtection,
+  findProtectionKeyByDatasource
+};

package/lib/api/records-bulk.api.js

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Dataplane bulk record sync API (data-storage records/bulk)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+const { createDataplaneApiClient } = require('./index');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+
+/**
+ * Bulk sync external records for a datasource.
+ * POST /api/v1/data-storage/{sourceIdOrKey}/records/bulk
+ * @requiresPermission {Dataplane} external-data-source:sync
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {string} sourceIdOrKey
+ * @param {Object} authConfig
+ * @param {import('./types/records-bulk.types').ExternalRecordBulkRequest} body
+ * @returns {Promise<import('./types/records-bulk.types').ExternalRecordBulkResponse>}
+ */
+async function bulkSyncRecords(dataplaneUrl, sourceIdOrKey, authConfig, body) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.post(
+    `/api/v1/data-storage/${encodeURIComponent(sourceIdOrKey)}/records/bulk`,
+    { body }
+  );
+  if (res && res.success === false) {
+    const msg =
+      res.formattedError ||
+      res.error ||
+      `Bulk sync failed (HTTP ${res.status || 0})`;
+    throw new Error(msg);
+  }
+  const payload = unwrapApiData(res);
+  if (!payload || typeof payload !== 'object') {
+    throw new Error('Bulk sync returned an unexpected response shape');
+  }
+  return payload;
+}
+
+module.exports = {
+  bulkSyncRecords
+};

package/lib/api/records-search-parse.js

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview Normalize dataplane Records Search client responses
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * Unwrap ApiClient `{ success, data: { data, meta, links } }` to a flat search result.
+ * @param {Object} response - Raw client.post result
+ * @returns {{ success: boolean, data: Array, meta: Object, links?: Object, status?: number, error?: string, formattedError?: string }}
+ */
+function normalizeRecordsSearchClientResponse(response) {
+  if (!response || response.success !== true) {
+    return response || { success: false, data: [], meta: {} };
+  }
+
+  const body = response.data;
+  if (body && typeof body === 'object' && Array.isArray(body.data)) {
+    return {
+      success: true,
+      data: body.data,
+      meta: body.meta && typeof body.meta === 'object' ? body.meta : {},
+      links: body.links,
+      status: response.status
+    };
+  }
+
+  if (Array.isArray(body)) {
+    return {
+      success: true,
+      data: body,
+      meta: response.meta && typeof response.meta === 'object' ? response.meta : {},
+      status: response.status
+    };
+  }
+
+  return {
+    success: true,
+    data: [],
+    meta: body && typeof body === 'object' && body.meta ? body.meta : {},
+    status: response.status
+  };
+}
+
+module.exports = {
+  normalizeRecordsSearchClientResponse
+};

package/lib/api/records-search.api.js

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Dataplane Records Search API
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+const { createDataplaneApiClient } = require('./index');
+const { normalizeRecordsSearchClientResponse } = require('./records-search-parse');
+
+/**
+ * Search records across datasources (governed read path).
+ * POST /api/v1/records/search
+ * @requiresPermission {Dataplane} record:search
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {import('./types/records-search.types').RecordsSearchRequest} body
+ * @returns {Promise<{ success: boolean, data: Array, meta: Object, links?: Object, status?: number }>}
+ */
+async function searchRecords(dataplaneUrl, authConfig, body) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const raw = await client.post('/api/v1/records/search', { body });
+  return normalizeRecordsSearchClientResponse(raw);
+}
+
+module.exports = {
+  searchRecords,
+  normalizeRecordsSearchClientResponse
+};

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

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Agent metadata validation API types (dataplane 404.5)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+/**
+ * @typedef {'info' | 'warning' | 'error'} AgentValidationFindingSeverity
+ */
+
+/**
+ * @typedef {Object} AgentValidationFinding
+ * @property {AgentValidationFindingSeverity} severity
+ * @property {string} code
+ * @property {string} message
+ * @property {string} [field]
+ * @property {string} [recommendation]
+ */
+
+/**
+ * @typedef {'pending' | 'passed' | 'warning' | 'failed'} AgentValidationStatus
+ */
+
+/**
+ * @typedef {'trusted' | 'usableWithWarnings' | 'notTrusted' | 'pending'} AgentTrustDecision
+ */
+
+/**
+ * @typedef {Object} AgentMetadataValidationResult
+ * @property {AgentValidationStatus} status
+ * @property {AgentTrustDecision} trustDecision
+ * @property {number} confidence
+ * @property {string} summary
+ * @property {AgentValidationFinding[]} findings
+ * @property {string} validatedAt - ISO 8601
+ * @property {string} inputHash
+ * @property {string} contractVersion
+ */
+
+/**
+ * @typedef {Object} AgentMetadataValidationRunRequest
+ * @property {boolean} [forceRevalidate]
+ * @property {Object<string, Object>} [peerDatasourceConfigs]
+ */
+
+/**
+ * @typedef {Object} AgentMetadataValidationRunResponse
+ * @property {string} id
+ * @property {string} externalDataSourceId
+ * @property {string} datasourceKey
+ * @property {AgentMetadataValidationResult} result
+ * @property {boolean} [reused]
+ */
+
+/**
+ * @typedef {Object} AgentMetadataValidationHistoryItem
+ * @property {string} id
+ * @property {string} inputHash
+ * @property {string} contractVersion
+ * @property {AgentTrustDecision} trustDecision
+ * @property {AgentValidationStatus} validationStatus
+ * @property {number} confidence
+ * @property {string} validatedAt
+ * @property {boolean} isLatest
+ */
+
+module.exports = {};