@aifabrix/builder 2.44.6 → 2.45.5

package/lib/api/index.js

@@ -20,7 +20,7 @@ class ApiClient {
    * @param {string} [authConfig.type] - Auth type ('bearer' | 'client-token')
    * @param {string} [authConfig.token] - Bearer token
    */
-  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 +30,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
+    });
   }
 
   /**
@@ -78,6 +97,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,6 +139,7 @@ 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);
 
@@ -167,6 +188,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 +216,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 +247,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 +277,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 +295,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/pipeline.api.js

@@ -4,7 +4,7 @@
  * @version 2.0.0
  */
 
-const { ApiClient } = require('./index');
+const { ApiClient, createDataplaneApiClient } = require('./index');
 const { postValidationRunAndOptionalPoll } = require('./validation-runner');
 
 /**
@@ -127,7 +127,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 +147,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 }
   });
@@ -247,7 +247,7 @@ async function testDatasourceViaPipeline({ dataplaneUrl, systemKey, datasourceKe
  */
 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,30 @@
+/**
+ * @fileoverview Dataplane bulk record sync API (data-storage records/bulk)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+const { createDataplaneApiClient } = require('./index');
+
+/**
+ * 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);
+  return await client.post(
+    `/api/v1/data-storage/${encodeURIComponent(sourceIdOrKey)}/records/bulk`,
+    { body }
+  );
+}
+
+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 = {};

package/lib/api/types/audit.types.js

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Audit API type definitions (dataplane read-only audit queries)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+/**
+ * Paginated list meta (miso-client shape).
+ * @typedef {Object} AuditListMeta
+ * @property {number} totalItems
+ * @property {number} [currentPage]
+ * @property {number} [pageSize]
+ */
+
+/**
+ * CIP execution list item (abbreviated).
+ * @typedef {Object} AuditExecutionListItem
+ * @property {string} id
+ * @property {string} [datasourceKey]
+ * @property {string} [operation]
+ * @property {string} [correlationId]
+ * @property {'captured'|'disabled'} rbacAuditStatus
+ * @property {'captured'|'disabled'} abacAuditStatus
+ * @property {import('./audit.types').ForeignKeyReference} [rbacDecision]
+ * @property {import('./audit.types').ForeignKeyReference} [abacTrace]
+ */
+
+/**
+ * @typedef {Object} ForeignKeyReference
+ * @property {string} [id]
+ * @property {string} [key]
+ * @property {string} [name]
+ */
+
+/**
+ * RBAC decision list item.
+ * @typedef {Object} AuditRbacDecisionListItem
+ * @property {string} id
+ * @property {import('./audit.types').ForeignKeyReference} [executionId]
+ * @property {string} [reason]
+ * @property {string} [decision]
+ */
+
+/**
+ * ABAC trace list item.
+ * @typedef {Object} AuditAbacTraceListItem
+ * @property {string} id
+ * @property {import('./audit.types').ForeignKeyReference} [executionId]
+ * @property {string} [decision]
+ * @property {string} [reason]
+ */
+
+/**
+ * One matrix row result.
+ * @typedef {Object} AuditEvidenceMatrixRow
+ * @property {number} row
+ * @property {'passed'|'failed'} status
+ * @property {string} detail
+ * @property {string} [code]
+ */
+
+/**
+ * Verifier output (407.3).
+ * @typedef {Object} AuditEvidenceVerification
+ * @property {'passed'|'failed'} status
+ * @property {string} datasourceKey
+ * @property {string|null} correlationId
+ * @property {string[]} executionIds
+ * @property {AuditEvidenceMatrixRow[]} matrix
+ */
+
+module.exports = {};

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

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Dataplane health API type definitions
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+/**
+ * Dataplane health JSON payload (public, no auth — `security: []` on dataplane).
+ * Matches `app/schemas/common.py` `HealthResponse` in aifabrix-dataplane (plan 403.0).
+ * @typedef {Object} DataplaneHealthPayload
+ * @property {string} status - 'healthy' or 'unhealthy'
+ * @property {string} service - Service name (e.g. 'dataplane')
+ * @property {string} version - Dataplane semver (always present)
+ * @property {string} [message] - Optional probe message (e.g. 'pong')
+ * @property {string} [minBuilderCliVersion] - Minimum supported Builder CLI semver; omitted when not enforced
+ */
+
+/**
+ * Parsed health snapshot used by Builder CLI cache + UX.
+ * @typedef {Object} DataplaneHealthSnapshot
+ * @property {string} status - 'healthy' / 'unhealthy' / 'unknown'
+ * @property {string} [version] - Dataplane version (undefined when probe failed)
+ * @property {string} [minBuilderCliVersion] - Trimmed minimum required Builder CLI semver (undefined when not enforced)
+ * @property {string|null} [endpoint] - Dataplane endpoint path that answered (e.g. '/api/v1/health' or '/health')
+ */
+
+module.exports = {};

package/lib/api/types/dimensions.types.js

@@ -11,6 +11,7 @@
  * @property {string} displayName
  * @property {string} [description]
  * @property {'string'|'number'|'boolean'} dataType
+ * @property {'static'|'dynamic'|'both'} [valueType]
  * @property {boolean} [isRequired]
  */
 
@@ -22,6 +23,7 @@
  * @property {string} displayName
  * @property {string|null} [description]
  * @property {'string'|'number'|'boolean'} dataType
+ * @property {'static'|'dynamic'|'both'} [valueType]
  * @property {boolean} isRequired
  * @property {string|null} [createdBy]
  * @property {string|null} [updatedBy]

package/lib/api/types/governance-scenarios.types.js

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Governance scenario acceptance API types
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+/**
+ * @typedef {Object} GovernanceScenariosRunRequest
+ * @property {string} systemKey
+ * @property {Object} pack - Inline governance scenario pack document
+ * @property {string[]} [scenarios] - Optional subset of scenario ids
+ */
+
+/**
+ * @typedef {Object} GovernanceScenarioResult
+ * @property {string} id
+ * @property {'pass'|'fail'} status
+ * @property {string} verdict
+ * @property {string} subjectUserId
+ * @property {string} subjectDisplayName
+ * @property {string[]} subjectGroups
+ * @property {number} visibleKeyCount
+ * @property {string[]} unexpectedVisibleKeys
+ * @property {string[]} missingRequiredKeys
+ * @property {number} excludedAbac
+ * @property {number} excludedFilter
+ * @property {string} [failureReason]
+ * @property {string} [fixHint]
+ * @property {string} [auditRef]
+ */
+
+/**
+ * @typedef {Object} GovernanceScenariosRunResponse
+ * @property {string} packKey
+ * @property {{ total: number, passed: number, failed: number }} summary
+ * @property {GovernanceScenarioResult[]} scenarios
+ */
+
+module.exports = {};