@aifabrix/builder 2.50.0 → 2.51.1

package/lib/api/evidence-kinds.api.js

@@ -0,0 +1,128 @@
+/**
+ * @fileoverview Evidence kinds API (Controller /api/v1/evidence-kinds)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { ApiClient } = require('./index');
+
+const BASE = '/api/v1/evidence-kinds';
+
+/**
+ * List evidence kinds (paginated)
+ * @requiresPermission {Controller} evidence-kinds:read
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {Object} [options]
+ * @returns {Promise<Object>}
+ */
+async function listEvidenceKinds(controllerUrl, authConfig, options = {}) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.get(BASE, { params: options });
+}
+
+/**
+ * Get an evidence kind by id or key
+ * @requiresPermission {Controller} evidence-kinds:read
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {string} evidenceKindIdOrKey
+ * @returns {Promise<Object>}
+ */
+async function getEvidenceKind(controllerUrl, authConfig, evidenceKindIdOrKey) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.get(`${BASE}/${encodeURIComponent(evidenceKindIdOrKey)}`);
+}
+
+/**
+ * @param {Object} payload
+ * @param {string} key
+ * @param {*} value
+ * @returns {void}
+ */
+function assignOptionalString(payload, key, value) {
+  if (value !== undefined && value !== null && value !== '') {
+    payload[key] = value;
+  }
+}
+
+/**
+ * @param {import('./types/evidence-kinds.types').CreateEvidenceKindRequest} body
+ * @returns {Object}
+ */
+function buildCreateEvidenceKindBody(body) {
+  const payload = {
+    key: body.key,
+    domainKey: body.domainKey,
+    displayName: body.displayName,
+    purpose: body.purpose
+  };
+  assignOptionalString(payload, 'description', body.description);
+  assignOptionalString(payload, 'expectedUse', body.expectedUse);
+  assignOptionalString(payload, 'source', body.source);
+  if (body.defaultSeverity) payload.defaultSeverity = body.defaultSeverity;
+  if (body.requiresApproval !== undefined && body.requiresApproval !== null) {
+    payload.requiresApproval = Boolean(body.requiresApproval);
+  }
+  if (body.isActive !== undefined && body.isActive !== null) {
+    payload.isActive = Boolean(body.isActive);
+  }
+  if (body.sortOrder !== undefined && body.sortOrder !== null) {
+    payload.sortOrder = Number(body.sortOrder);
+  }
+  if (body.metadata && typeof body.metadata === 'object') {
+    payload.metadata = body.metadata;
+  }
+  return payload;
+}
+
+/**
+ * Create an evidence kind
+ * @requiresPermission {Controller} evidence-kinds:create
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {import('./types/evidence-kinds.types').CreateEvidenceKindRequest} body
+ * @returns {Promise<Object>}
+ */
+async function createEvidenceKind(controllerUrl, authConfig, body) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.post(BASE, { body: buildCreateEvidenceKindBody(body) });
+}
+
+/**
+ * Create-if-missing (idempotent): if an evidence kind already exists for the key, return success.
+ * @requiresPermission {Controller} evidence-kinds:read + evidence-kinds:create
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {import('./types/evidence-kinds.types').CreateEvidenceKindRequest} body
+ * @returns {Promise<{ created: boolean, response: Object }>}
+ */
+async function createEvidenceKindIdempotent(controllerUrl, authConfig, body) {
+  const key = String(body?.key || '').trim();
+  if (!key) {
+    throw new Error('Evidence kind key is required');
+  }
+  const getRes = await getEvidenceKind(controllerUrl, authConfig, key);
+  if (getRes && getRes.success === true) {
+    return { created: false, response: getRes };
+  }
+  const createRes = await createEvidenceKind(controllerUrl, authConfig, body);
+  if (createRes && createRes.success === true) {
+    return { created: true, response: createRes };
+  }
+  const msg = createRes?.error || createRes?.formattedError || 'Failed to create evidence kind';
+  throw new Error(msg);
+}
+
+module.exports = {
+  listEvidenceKinds,
+  getEvidenceKind,
+  createEvidenceKind,
+  createEvidenceKindIdempotent
+};

package/lib/api/evidence.api.js

@@ -162,11 +162,67 @@ async function loadEvidenceBulk(dataplaneUrl, authConfig, rows, options = {}) {
   };
 }
 
+/**
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} evidenceIdOrKey
+ * @param {Object} [options]
+ * @returns {Promise<Object>}
+ */
+async function validateEvidenceCandidate(dataplaneUrl, authConfig, evidenceIdOrKey, options = {}) {
+  const client = createEvidenceClient(dataplaneUrl, authConfig, options);
+  const res = assertApiSuccess(
+    await client.post(`${BASE}/${encodeURIComponent(evidenceIdOrKey)}/validate`, { body: {} }),
+    'Validate evidence'
+  );
+  return unwrapBody(res);
+}
+
+/**
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} evidenceIdOrKey
+ * @param {{ comment?: string }} [payload]
+ * @param {Object} [options]
+ * @returns {Promise<Object>}
+ */
+async function certifyEvidenceCandidate(dataplaneUrl, authConfig, evidenceIdOrKey, payload = {}, options = {}) {
+  const client = createEvidenceClient(dataplaneUrl, authConfig, options);
+  const body = {};
+  if (payload && typeof payload.comment === 'string' && payload.comment.trim()) {
+    body.comment = payload.comment.trim();
+  }
+  const res = assertApiSuccess(
+    await client.post(`${BASE}/${encodeURIComponent(evidenceIdOrKey)}/certify`, { body }),
+    'Certify evidence'
+  );
+  return unwrapBody(res);
+}
+
+/**
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} evidenceIdOrKey
+ * @param {Object} [options]
+ * @returns {Promise<Object>}
+ */
+async function activateEvidenceCandidate(dataplaneUrl, authConfig, evidenceIdOrKey, options = {}) {
+  const client = createEvidenceClient(dataplaneUrl, authConfig, options);
+  const res = assertApiSuccess(
+    await client.post(`${BASE}/${encodeURIComponent(evidenceIdOrKey)}/activate`, { body: {} }),
+    'Activate evidence'
+  );
+  return unwrapBody(res);
+}
+
 module.exports = {
   listEvidence,
   getEvidence,
   insertEvidence,
   updateEvidence,
   deleteEvidence,
-  loadEvidenceBulk
+  loadEvidenceBulk,
+  validateEvidenceCandidate,
+  certifyEvidenceCandidate,
+  activateEvidenceCandidate
 };

package/lib/api/index.js

@@ -79,7 +79,7 @@ class ApiClient {
       headers['Content-Type'] = 'application/json';
     }
 
-    // User token (bearer) → Authorization: Bearer; application token (client-token) → x-client-token
+    // User token (bearer) → Authorization: Bearer; app token (client-token) → x-client-token.
     if (this.authConfig.type === 'bootstrap' && this.authConfig.encryptionKey) {
       headers['x-encryption-key'] = String(this.authConfig.encryptionKey);
     } else if (this.authConfig.token) {
@@ -160,7 +160,10 @@ class ApiClient {
       transport.timeoutMs = options.timeoutMs;
     }
 
-    if (this.authConfig.type === 'bearer' || this.authConfig.type === 'client-token') {
+    if (
+      this.authConfig.type === 'bearer' ||
+      this.authConfig.type === 'client-token'
+    ) {
       // Pass full authConfig to enable proper token refresh using controller URL
       return await authenticatedApiCall(url, transport, this.authConfig);
     }
@@ -213,7 +216,10 @@ class ApiClient {
       requestOptions.timeoutMs = options.timeoutMs;
     }
 
-    if (this.authConfig.type === 'bearer' || this.authConfig.type === 'client-token') {
+    if (
+      this.authConfig.type === 'bearer' ||
+      this.authConfig.type === 'client-token'
+    ) {
       // Pass full authConfig to enable proper token refresh using controller URL
       return await authenticatedApiCall(url, requestOptions, this.authConfig);
     }
@@ -241,7 +247,9 @@ class ApiClient {
       body: formData
     };
 
-    const hasToken = this.authConfig.type === 'bearer' || this.authConfig.type === 'client-token';
+    const hasToken =
+      this.authConfig.type === 'bearer' ||
+      this.authConfig.type === 'client-token';
     if (hasToken && this.authConfig.token) {
       return await authenticatedApiCall(url, requestOptions, this.authConfig);
     }
@@ -272,7 +280,10 @@ class ApiClient {
       requestOptions.body = JSON.stringify(options.body);
     }
 
-    if (this.authConfig.type === 'bearer' || this.authConfig.type === 'client-token') {
+    if (
+      this.authConfig.type === 'bearer' ||
+      this.authConfig.type === 'client-token'
+    ) {
       // Pass full authConfig to enable proper token refresh using controller URL
       return await authenticatedApiCall(url, requestOptions, this.authConfig);
     }
@@ -303,7 +314,10 @@ class ApiClient {
       requestOptions.body = JSON.stringify(options.body);
     }
 
-    if (this.authConfig.type === 'bearer' || this.authConfig.type === 'client-token') {
+    if (
+      this.authConfig.type === 'bearer' ||
+      this.authConfig.type === 'client-token'
+    ) {
       // Pass full authConfig to enable proper token refresh using controller URL
       return await authenticatedApiCall(url, requestOptions, this.authConfig);
     }
@@ -329,7 +343,10 @@ class ApiClient {
       headers
     };
 
-    if (this.authConfig.type === 'bearer' || this.authConfig.type === 'client-token') {
+    if (
+      this.authConfig.type === 'bearer' ||
+      this.authConfig.type === 'client-token'
+    ) {
       // Pass full authConfig to enable proper token refresh using controller URL
       return await authenticatedApiCall(url, requestOptions, this.authConfig);
     }

package/lib/api/pipeline.api.js

@@ -247,11 +247,53 @@ async function testDatasourceViaPipeline({ dataplaneUrl, systemKey, datasourceKe
  * @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) {
+/** Multi-datasource publish often exceeds the default 30s HTTP timeout. */
+const PIPELINE_UPLOAD_TIMEOUT_MS = 300000;
+const PIPELINE_UPLOAD_TIMEOUT_MIN_MS = 5000;
+const PIPELINE_UPLOAD_TIMEOUT_MAX_MS = 45 * 60 * 1000;
+
+/**
+ * Resolve pipeline upload timeout (ms) for HTTP + dataplane budget.
+ * @param {number|string|undefined|null} raw
+ * @returns {number}
+ */
+function resolvePipelineUploadTimeoutMs(raw) {
+  if (raw === undefined || raw === null || raw === '') {
+    return PIPELINE_UPLOAD_TIMEOUT_MS;
+  }
+  const n = typeof raw === 'number' ? raw : Number(raw);
+  if (!Number.isFinite(n) || n <= 0) {
+    throw new Error(
+      `--timeout must be a positive number of milliseconds (got ${String(raw)})`
+    );
+  }
+  return Math.min(
+    PIPELINE_UPLOAD_TIMEOUT_MAX_MS,
+    Math.max(PIPELINE_UPLOAD_TIMEOUT_MIN_MS, Math.floor(n))
+  );
+}
+
+/**
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {Object} payload
+ * @param {Object} [options]
+ * @param {number|string} [options.timeoutMs] - HTTP + dataplane publish budget (default 300000)
+ */
+async function uploadApplicationViaPipeline(
+  dataplaneUrl,
+  authConfig,
+  payload,
+  options = {}
+) {
   const body = { ...payload, status: payload.status ?? 'draft' };
+  const timeoutMs = resolvePipelineUploadTimeoutMs(options.timeoutMs);
   const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post('/api/v1/pipeline/upload', {
-    body
+    body,
+    timeoutMs,
+    params: { timeoutMs: String(timeoutMs) },
+    headers: { 'X-Aifabrix-Timeout-Ms': String(timeoutMs) }
   });
 }
 
@@ -264,6 +306,8 @@ module.exports = {
   validatePipelineConfig,
   testSystemViaPipeline,
   testDatasourceViaPipeline,
-  uploadApplicationViaPipeline
+  uploadApplicationViaPipeline,
+  resolvePipelineUploadTimeoutMs,
+  PIPELINE_UPLOAD_TIMEOUT_MS
 };
 

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

@@ -7,6 +7,26 @@
 const { createDataplaneApiClient } = require('./index');
 const { unwrapApiData } = require('../utils/external-system-readiness-core');
 
+/** Default HTTP budget for records/bulk (ABAC projection can exceed 30s under load). */
+const DEFAULT_BULK_SYNC_TIMEOUT_MS = 120000;
+
+/**
+ * Resolve per-request timeout for bulk sync.
+ * @param {Object} [transportOpts]
+ * @returns {number}
+ */
+function resolveBulkSyncTimeoutMs(transportOpts = {}) {
+  const raw = transportOpts.timeoutMs ?? transportOpts.timeout;
+  if (raw === undefined || raw === null || raw === '') {
+    return DEFAULT_BULK_SYNC_TIMEOUT_MS;
+  }
+  const n = typeof raw === 'number' ? raw : parseInt(String(raw), 10);
+  if (!Number.isFinite(n) || n <= 0) {
+    return DEFAULT_BULK_SYNC_TIMEOUT_MS;
+  }
+  return n;
+}
+
 /**
  * Bulk sync external records for a datasource.
  * POST /api/v1/data-storage/{sourceIdOrKey}/records/bulk
@@ -16,13 +36,16 @@ const { unwrapApiData } = require('../utils/external-system-readiness-core');
  * @param {string} sourceIdOrKey
  * @param {Object} authConfig
  * @param {import('./types/records-bulk.types').ExternalRecordBulkRequest} body
+ * @param {Object} [transportOpts]
+ * @param {number} [transportOpts.timeoutMs] - Per-request HTTP timeout (default 120000)
  * @returns {Promise<import('./types/records-bulk.types').ExternalRecordBulkResponse>}
  */
-async function bulkSyncRecords(dataplaneUrl, sourceIdOrKey, authConfig, body) {
+async function bulkSyncRecords(dataplaneUrl, sourceIdOrKey, authConfig, body, transportOpts = {}) {
   const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const timeoutMs = resolveBulkSyncTimeoutMs(transportOpts);
   const res = await client.post(
     `/api/v1/data-storage/${encodeURIComponent(sourceIdOrKey)}/records/bulk`,
-    { body }
+    { body, timeoutMs }
   );
   if (res && res.success === false) {
     const msg =
@@ -39,5 +62,7 @@ async function bulkSyncRecords(dataplaneUrl, sourceIdOrKey, authConfig, body) {
 }
 
 module.exports = {
-  bulkSyncRecords
+  bulkSyncRecords,
+  resolveBulkSyncTimeoutMs,
+  DEFAULT_BULK_SYNC_TIMEOUT_MS
 };

package/lib/api/resource-types.api.js

@@ -12,7 +12,7 @@ const BASE = '/api/v1/resource-types';
 
 /**
  * List resource types (paginated)
- * @requiresPermission {Controller} resourceTypes:read
+ * @requiresPermission {Controller} resource-types:read
  * @async
  * @function listResourceTypes
  * @param {string} controllerUrl
@@ -34,7 +34,7 @@ async function listResourceTypes(controllerUrl, authConfig, options = {}) {
 
 /**
  * Get a resource type by id or key
- * @requiresPermission {Controller} resourceTypes:read
+ * @requiresPermission {Controller} resource-types:read
  * @async
  * @function getResourceType
  * @param {string} controllerUrl
@@ -49,7 +49,7 @@ async function getResourceType(controllerUrl, authConfig, resourceTypeIdOrKey) {
 
 /**
  * Create a resource type
- * @requiresPermission {Controller} resourceTypes:create
+ * @requiresPermission {Controller} resource-types:create
  * @async
  * @function createResourceType
  * @param {string} controllerUrl
@@ -75,7 +75,7 @@ async function createResourceType(controllerUrl, authConfig, body) {
 
 /**
  * Create-if-missing (idempotent): if a resource type already exists for the key, return success.
- * @requiresPermission {Controller} resourceTypes:read + resourceTypes:create
+ * @requiresPermission {Controller} resource-types:read + resource-types:create
  * @async
  * @function createResourceTypeIdempotent
  * @param {string} controllerUrl

package/lib/api/roles.api.js

@@ -0,0 +1,121 @@
+/**
+ * @fileoverview Business roles API (Controller /api/v1/roles)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { ApiClient } = require('./index');
+
+const BASE = '/api/v1/roles';
+
+/**
+ * List business roles (paginated)
+ * @requiresPermission {Controller} roles:read
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {Object} [options]
+ * @returns {Promise<Object>}
+ */
+async function listRoles(controllerUrl, authConfig, options = {}) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.get(BASE, { params: options });
+}
+
+/**
+ * Get a business role by id or key
+ * @requiresPermission {Controller} roles:read
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {string} roleIdOrKey
+ * @returns {Promise<Object>}
+ */
+async function getRole(controllerUrl, authConfig, roleIdOrKey) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.get(`${BASE}/${encodeURIComponent(roleIdOrKey)}`);
+}
+
+/**
+ * @param {Object} payload
+ * @param {string} key
+ * @param {*} value
+ * @returns {void}
+ */
+function assignOptionalString(payload, key, value) {
+  if (value !== undefined && value !== null && value !== '') {
+    payload[key] = value;
+  }
+}
+
+/**
+ * @param {import('./types/roles.types').CreateBusinessRoleRequest} body
+ * @returns {Object}
+ */
+function buildCreateRoleBody(body) {
+  const payload = {
+    key: body.key,
+    domainKey: body.domainKey,
+    displayName: body.displayName
+  };
+  assignOptionalString(payload, 'description', body.description);
+  assignOptionalString(payload, 'purpose', body.purpose);
+  assignOptionalString(payload, 'businessOutcome', body.businessOutcome);
+  assignOptionalString(payload, 'source', body.source);
+  if (body.isActive !== undefined && body.isActive !== null) {
+    payload.isActive = Boolean(body.isActive);
+  }
+  if (body.metadata && typeof body.metadata === 'object') {
+    payload.metadata = body.metadata;
+  }
+  return payload;
+}
+
+/**
+ * Create a business role
+ * @requiresPermission {Controller} roles:create
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {import('./types/roles.types').CreateBusinessRoleRequest} body
+ * @returns {Promise<Object>}
+ */
+async function createRole(controllerUrl, authConfig, body) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.post(BASE, { body: buildCreateRoleBody(body) });
+}
+
+/**
+ * Create-if-missing (idempotent): if a role already exists for the key, return success.
+ * @requiresPermission {Controller} roles:read + roles:create
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {import('./types/roles.types').CreateBusinessRoleRequest} body
+ * @returns {Promise<{ created: boolean, response: Object }>}
+ */
+async function createRoleIdempotent(controllerUrl, authConfig, body) {
+  const key = String(body?.key || '').trim();
+  if (!key) {
+    throw new Error('Role key is required');
+  }
+  const getRes = await getRole(controllerUrl, authConfig, key);
+  if (getRes && getRes.success === true) {
+    return { created: false, response: getRes };
+  }
+  const createRes = await createRole(controllerUrl, authConfig, body);
+  if (createRes && createRes.success === true) {
+    return { created: true, response: createRes };
+  }
+  const msg = createRes?.error || createRes?.formattedError || 'Failed to create role';
+  throw new Error(msg);
+}
+
+module.exports = {
+  listRoles,
+  getRole,
+  createRole,
+  createRoleIdempotent
+};

package/lib/api/types/evidence-kinds.types.js

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Evidence kind API type definitions (Controller /api/v1/evidence-kinds)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+/**
+ * Create evidence kind request body (API shape uses domainKey)
+ * @typedef {Object} CreateEvidenceKindRequest
+ * @property {string} key - Catalog key (lowercase, digits, underscores)
+ * @property {string} domainKey - Enterprise domain key
+ * @property {string} displayName - Human-readable name
+ * @property {string} purpose - Purpose (required by Controller)
+ * @property {string} [description] - Optional description
+ * @property {string} [expectedUse] - Expected use guidance
+ * @property {string} [defaultSeverity] - low | medium | high | critical
+ * @property {boolean} [requiresApproval] - Approval flag
+ * @property {boolean} [isActive] - Active flag
+ * @property {number} [sortOrder] - Sort order
+ * @property {string} [source] - Provenance source
+ * @property {Object} [metadata] - Extensions
+ */
+
+/**
+ * Evidence kind record
+ * @typedef {Object} EvidenceKindRecord
+ * @property {string} id - Controller id
+ * @property {string} key - Catalog key
+ * @property {string} domainKey - Enterprise domain key
+ * @property {string} displayName - Display name
+ * @property {string} purpose - Purpose
+ * @property {string} [description] - Description
+ * @property {string} [expectedUse] - Expected use
+ * @property {string} [defaultSeverity] - Default severity
+ * @property {boolean} requiresApproval - Approval flag
+ * @property {boolean} isActive - Active flag
+ * @property {number} sortOrder - Sort order
+ * @property {string} [source] - Source
+ * @property {Object} [metadata] - Metadata
+ */
+
+module.exports = {};