@aifabrix/builder 2.45.5 → 2.47.0

package/lib/api/lifecycle.api.js

@@ -0,0 +1,98 @@
+/**
+ * @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;
+}
+
+async function runSystemVerifyTrust(dataplaneUrl, authConfig, systemKey, body = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.post(
+    `/api/v1/external/systems/${encodeURIComponent(systemKey)}/verify-trust`,
+    { body }
+  );
+  if (res && res.success === false) {
+    const msg =
+      (res.error && (res.error.formattedError || res.error.error || res.error.message)) ||
+      res.formattedError ||
+      'verify-trust request failed';
+    throw new Error(msg);
+  }
+  const unwrapped = unwrapApiData(res);
+  if (!unwrapped || !unwrapped.systemKey) {
+    throw new Error('verify-trust returned an unexpected response shape');
+  }
+  return unwrapped;
+}
+
+module.exports = {
+  getSystemLifecycleReport,
+  runSystemLifecycle,
+  runSystemVerifyTrust
+};

package/lib/api/pipeline.api.js

@@ -6,6 +6,7 @@
 
 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);
 }
 
 /**
@@ -242,6 +243,7 @@ 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
  */

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

@@ -5,6 +5,7 @@
  */
 
 const { createDataplaneApiClient } = require('./index');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
 
 /**
  * Bulk sync external records for a datasource.
@@ -19,10 +20,22 @@ const { createDataplaneApiClient } = require('./index');
  */
 async function bulkSyncRecords(dataplaneUrl, sourceIdOrKey, authConfig, body) {
   const client = createDataplaneApiClient(dataplaneUrl, authConfig);
-  return await client.post(
+  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 = {

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

@@ -0,0 +1,107 @@
+/**
+ * @fileoverview Resource types API (Controller /api/v1/resource-types)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { ApiClient } = require('./index');
+
+const BASE = '/api/v1/resource-types';
+
+/**
+ * List resource types (paginated)
+ * @requiresPermission {Controller} resourceTypes:read
+ * @async
+ * @function listResourceTypes
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {Object} [options]
+ * @param {number} [options.page]
+ * @param {number} [options.pageSize]
+ * @param {string} [options.sort]
+ * @param {string} [options.filter]
+ * @param {string} [options.search]
+ * @param {string} [options.category]
+ * @param {string} [options.status]
+ * @returns {Promise<Object>}
+ */
+async function listResourceTypes(controllerUrl, authConfig, options = {}) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.get(BASE, { params: options });
+}
+
+/**
+ * Get a resource type by id or key
+ * @requiresPermission {Controller} resourceTypes:read
+ * @async
+ * @function getResourceType
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {string} resourceTypeIdOrKey
+ * @returns {Promise<Object>}
+ */
+async function getResourceType(controllerUrl, authConfig, resourceTypeIdOrKey) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.get(`${BASE}/${encodeURIComponent(resourceTypeIdOrKey)}`);
+}
+
+/**
+ * Create a resource type
+ * @requiresPermission {Controller} resourceTypes:create
+ * @async
+ * @function createResourceType
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {import('./types/resource-types.types').CreateResourceTypeRequest} body
+ * @returns {Promise<Object>}
+ */
+async function createResourceType(controllerUrl, authConfig, body) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  const payload = {
+    key: body.key,
+    displayName: body.displayName
+  };
+  if (body.description !== undefined && body.description !== null && body.description !== '') {
+    payload.description = body.description;
+  }
+  if (body.category) payload.category = body.category;
+  if (body.defaultRiskLevel) payload.defaultRiskLevel = body.defaultRiskLevel;
+  if (body.status) payload.status = body.status;
+  return await client.post(BASE, { body: payload });
+}
+
+/**
+ * Create-if-missing (idempotent): if a resource type already exists for the key, return success.
+ * @requiresPermission {Controller} resourceTypes:read + resourceTypes:create
+ * @async
+ * @function createResourceTypeIdempotent
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {import('./types/resource-types.types').CreateResourceTypeRequest} body
+ * @returns {Promise<{ created: boolean, response: Object }>}
+ */
+async function createResourceTypeIdempotent(controllerUrl, authConfig, body) {
+  const key = String(body?.key || '').trim();
+  if (!key) {
+    throw new Error('Resource type key is required');
+  }
+  const getRes = await getResourceType(controllerUrl, authConfig, key);
+  if (getRes && getRes.success === true) {
+    return { created: false, response: getRes };
+  }
+  const createRes = await createResourceType(controllerUrl, authConfig, body);
+  if (createRes && createRes.success === true) {
+    return { created: true, response: createRes };
+  }
+  const msg = createRes?.error || createRes?.formattedError || 'Failed to create resource type';
+  throw new Error(msg);
+}
+
+module.exports = {
+  listResourceTypes,
+  getResourceType,
+  createResourceType,
+  createResourceTypeIdempotent
+};

package/lib/api/runtime-configuration.api.js

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Runtime configuration variable API (dataplane configuration_values)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+const { createDataplaneApiClient } = require('./index');
+
+/**
+ * GET /api/v1/external/systems/{systemIdOrKey}/configuration
+ * @requiresPermission {Dataplane} external-system:read
+ */
+async function getExternalSystemConfiguration(dataplaneUrl, systemIdOrKey, authConfig) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  return await client.get(`/api/v1/external/systems/${systemIdOrKey}/configuration`);
+}
+
+/**
+ * PUT /api/v1/external/systems/{systemIdOrKey}/configuration
+ * @requiresPermission {Dataplane} external-system:update
+ * @param {{ name: string, value?: string|null, kvKey?: string|null }} body
+ */
+async function putExternalSystemConfiguration(dataplaneUrl, systemIdOrKey, authConfig, body) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  return await client.put(`/api/v1/external/systems/${systemIdOrKey}/configuration`, { body });
+}
+
+/**
+ * GET /api/v1/external/{sourceIdOrKey}/configuration
+ * @requiresPermission {Dataplane} external-data-source:read
+ */
+async function getExternalDataSourceConfiguration(dataplaneUrl, sourceIdOrKey, authConfig) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  return await client.get(`/api/v1/external/${sourceIdOrKey}/configuration`);
+}
+
+/**
+ * GET /api/v1/external/systems/{systemIdOrKey}/configuration/resolved
+ * @requiresPermission {Dataplane} external-system:configuration:resolve
+ */
+async function getExternalSystemConfigurationResolved(dataplaneUrl, systemIdOrKey, authConfig) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  return await client.get(`/api/v1/external/systems/${systemIdOrKey}/configuration/resolved`);
+}
+
+/**
+ * GET /api/v1/external/{sourceIdOrKey}/configuration/resolved
+ * @requiresPermission {Dataplane} external-data-source:configuration:resolve
+ */
+async function getExternalDataSourceConfigurationResolved(dataplaneUrl, sourceIdOrKey, authConfig) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  return await client.get(`/api/v1/external/${sourceIdOrKey}/configuration/resolved`);
+}
+
+/**
+ * PUT /api/v1/external/{sourceIdOrKey}/configuration
+ * @requiresPermission {Dataplane} external-data-source:update
+ * @param {{ name: string, value?: string|null, kvKey?: string|null }} body
+ */
+async function putExternalDataSourceConfiguration(dataplaneUrl, sourceIdOrKey, authConfig, body) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  return await client.put(`/api/v1/external/${sourceIdOrKey}/configuration`, { body });
+}
+
+module.exports = {
+  getExternalSystemConfiguration,
+  getExternalSystemConfigurationResolved,
+  putExternalSystemConfiguration,
+  getExternalDataSourceConfiguration,
+  getExternalDataSourceConfigurationResolved,
+  putExternalDataSourceConfiguration
+};

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

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Resource type catalog API type definitions
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+/**
+ * Resource type category
+ * @typedef {'business'|'collaboration'|'governance'|'content'|'communication'|'people'} ResourceTypeCategory
+ */
+
+/**
+ * Resource type risk level
+ * @typedef {'low'|'medium'|'high'|'critical'} ResourceTypeRiskLevel
+ */
+
+/**
+ * Resource type lifecycle status
+ * @typedef {'draft'|'active'|'deprecated'|'retired'} ResourceTypeStatus
+ */
+
+/**
+ * Create resource type request body
+ * @typedef {Object} CreateResourceTypeRequest
+ * @property {string} key - Catalog key (lowercase, hyphens)
+ * @property {string} displayName - Human-readable name
+ * @property {string} [description] - Optional description
+ * @property {ResourceTypeCategory} [category] - Catalog category
+ * @property {ResourceTypeRiskLevel} [defaultRiskLevel] - Default risk level
+ * @property {ResourceTypeStatus} [status] - Lifecycle status
+ */
+
+/**
+ * Resource type record
+ * @typedef {Object} ResourceTypeRecord
+ * @property {string} id - Controller id
+ * @property {string} key - Catalog key
+ * @property {string} displayName - Display name
+ * @property {string} [description] - Description
+ * @property {ResourceTypeCategory} category - Category
+ * @property {ResourceTypeRiskLevel} defaultRiskLevel - Default risk
+ * @property {ResourceTypeStatus} status - Status
+ */
+
+module.exports = {};

package/lib/api/user-groups.api.js

@@ -9,20 +9,20 @@
 const { ApiClient } = require('./index');
 
 /**
- * Add user to group
+ * Add user to group (flexible path segments per plan 194)
  * @requiresPermission {Controller} users:update
  * @async
  * @param {string} controllerUrl
  * @param {Object} authConfig
- * @param {string} userId
- * @param {string} groupId
+ * @param {string} userIdOrEmail - UUID, email, or username
+ * @param {string} groupIdOrName - UUID or group name
  * @param {Object} [body]
  * @returns {Promise<Object>}
  */
-async function addUserToGroup(controllerUrl, authConfig, userId, groupId, body = {}) {
+async function addUserToGroup(controllerUrl, authConfig, userIdOrEmail, groupIdOrName, body = {}) {
   const client = new ApiClient(controllerUrl, authConfig);
   return await client.post(
-    `/api/v1/users/${encodeURIComponent(userId)}/groups/${encodeURIComponent(groupId)}`,
+    `/api/v1/users/${encodeURIComponent(userIdOrEmail)}/groups/${encodeURIComponent(groupIdOrName)}`,
     { body }
   );
 }
@@ -33,14 +33,14 @@ async function addUserToGroup(controllerUrl, authConfig, userId, groupId, body =
  * @async
  * @param {string} controllerUrl
  * @param {Object} authConfig
- * @param {string} userId
- * @param {string} groupId
+ * @param {string} userIdOrEmail - UUID, email, or username
+ * @param {string} groupIdOrName - UUID or group name
  * @returns {Promise<Object>}
  */
-async function removeUserFromGroup(controllerUrl, authConfig, userId, groupId) {
+async function removeUserFromGroup(controllerUrl, authConfig, userIdOrEmail, groupIdOrName) {
   const client = new ApiClient(controllerUrl, authConfig);
   return await client.delete(
-    `/api/v1/users/${encodeURIComponent(userId)}/groups/${encodeURIComponent(groupId)}`
+    `/api/v1/users/${encodeURIComponent(userIdOrEmail)}/groups/${encodeURIComponent(groupIdOrName)}`
   );
 }
 

package/lib/api/users.api.js

@@ -25,22 +25,22 @@ async function listUsers(controllerUrl, authConfig, options = {}) {
 }
 
 /**
- * Get user by id
+ * Get user by id, email, or username (controller path: userIdOrEmail)
  * @requiresPermission {Controller} users:read
  * @async
  * @param {string} controllerUrl
  * @param {Object} authConfig
- * @param {string} userId
+ * @param {string} userIdOrEmail - UUID, email, or username
  * @param {Object} [options]
  * @returns {Promise<Object>}
  */
-async function getUser(controllerUrl, authConfig, userId, options = {}) {
+async function getUser(controllerUrl, authConfig, userIdOrEmail, options = {}) {
   const client = new ApiClient(controllerUrl, authConfig);
   const params = {};
   if (options.includeGroups) {
     params.includeGroups = 'true';
   }
-  return await client.get(`${BASE}/${encodeURIComponent(userId)}`, { params });
+  return await client.get(`${BASE}/${encodeURIComponent(userIdOrEmail)}`, { params });
 }
 
 /**
@@ -73,17 +73,17 @@ async function updateUser(controllerUrl, authConfig, userId, body) {
 }
 
 /**
- * List groups for a user
+ * List groups for a user (controller path: userIdOrEmail)
  * @requiresPermission {Controller} users:read
  * @async
  * @param {string} controllerUrl
  * @param {Object} authConfig
- * @param {string} userId
+ * @param {string} userIdOrEmail - UUID, email, or username
  * @returns {Promise<Object>}
  */
-async function listUserGroups(controllerUrl, authConfig, userId) {
+async function listUserGroups(controllerUrl, authConfig, userIdOrEmail) {
   const client = new ApiClient(controllerUrl, authConfig);
-  return await client.get(`${BASE}/${encodeURIComponent(userId)}/groups`);
+  return await client.get(`${BASE}/${encodeURIComponent(userIdOrEmail)}/groups`);
 }
 
 module.exports = {

package/lib/api/validation-runner.js

@@ -22,6 +22,7 @@ const { createValidationPollHandlers } = require('../utils/validation-poll-ui');
  * @param {boolean} opts.useAsync
  * @param {boolean} opts.noAsync
  * @param {boolean} [opts.verbosePoll] - Throttled poll lines when no TTY poll UI (see validation-run-poll)
+ * @param {boolean} [opts.quietPollUi] - Suppress poll spinner/lines (orchestrated verify-* owns progress)
  * @param {Function} [opts.onPollProgress] - Extra hook: `(envelope, attemptIndex, meta)` during poll
  * @returns {Promise<{ envelope: Object|null, apiError: Object|null, pollTimedOut: boolean, incompleteNoAsync: boolean }>}
  */
@@ -60,7 +61,8 @@ async function postValidationRunAndOptionalPoll(opts) {
     const deadlineMs = Date.now() + remaining;
 
     const pollUi = createValidationPollHandlers(deadlineMs, {
-      subject: opts.pollSubject
+      subject: opts.pollSubject,
+      quiet: opts.quietPollUi === true
     });
     const mergeOnPollProgress =
       typeof opts.onPollProgress === 'function'

package/lib/api/wizard.api.js

@@ -205,6 +205,12 @@ async function getPlatformConfig(dataplaneUrl, authConfig, platformKey, config)
   });
 }
 
+/**
+ * Wizard AI generation can exceed the default 30s HTTP timeout (OpenAPI + LLM).
+ * @constant {number}
+ */
+const WIZARD_GENERATE_CONFIG_TIMEOUT_MS = 120000;
+
 /**
  * Generate configuration via AI (OpenAPI-based)
  * POST /api/v1/wizard/generate-config
@@ -235,7 +241,8 @@ async function getPlatformConfig(dataplaneUrl, authConfig, platformKey, config)
 async function generateConfig(dataplaneUrl, authConfig, config) {
   const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post('/api/v1/wizard/generate-config', {
-    body: config
+    body: config,
+    timeoutMs: WIZARD_GENERATE_CONFIG_TIMEOUT_MS
   });
 }
 
@@ -254,7 +261,8 @@ async function generateConfig(dataplaneUrl, authConfig, config) {
 async function generateConfigStream(dataplaneUrl, authConfig, config) {
   const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post('/api/v1/wizard/generate-config-stream', {
-    body: config
+    body: config,
+    timeoutMs: WIZARD_GENERATE_CONFIG_TIMEOUT_MS
   });
 }
 

package/lib/app/deploy-config.js

@@ -60,7 +60,10 @@ async function extractDeploymentConfig(options, _variables) {
   const { resolveEnvironment } = require('../core/config');
 
   const controllerUrl = await resolveControllerUrl();
-  const envKey = await resolveEnvironment();
+  const envKey =
+    options && options.envKey
+      ? String(options.envKey).trim().toLowerCase()
+      : await resolveEnvironment();
 
   const pollIntervalExplicit =
     options.pollInterval !== undefined && options.pollInterval !== null