@aifabrix/builder 2.44.6 → 2.45.5

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
+};

package/lib/api/datasources-core.api.js

@@ -4,81 +4,84 @@
  * @version 2.0.0
  */
 
-const { ApiClient } = require('./index');
+const { createDataplaneApiClient } = require('./index');
 
 /** @requiresPermission {Dataplane} external-system:read (datasource list) */
 async function listDatasources(dataplaneUrl, authConfig, options = {}) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.get('/api/v1/external', { params: options });
 }
 /** @requiresPermission {Dataplane} external-system:create */
 async function createDatasource(dataplaneUrl, authConfig, datasourceData) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post('/api/v1/external', { body: datasourceData });
 }
 /** @requiresPermission {Dataplane} external-system:read */
 async function getDatasource(dataplaneUrl, sourceIdOrKey, authConfig) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}`);
 }
 /** @requiresPermission {Dataplane} external-system:update */
 async function updateDatasource(dataplaneUrl, sourceIdOrKey, authConfig, updateData) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.put(`/api/v1/external/${sourceIdOrKey}`, { body: updateData });
 }
 /** @requiresPermission {Dataplane} external-system:delete */
 async function deleteDatasource(dataplaneUrl, sourceIdOrKey, authConfig) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.delete(`/api/v1/external/${sourceIdOrKey}`);
 }
 /** @requiresPermission {Dataplane} external-system:read */
 async function getDatasourceConfig(dataplaneUrl, sourceIdOrKey, authConfig) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/config`);
 }
 /** @requiresPermission {Dataplane} external-system:update */
 async function publishDatasource(dataplaneUrl, sourceIdOrKey, authConfig, publishData = {}) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/publish`, { body: publishData });
 }
 /** @requiresPermission {Dataplane} external-system:update */
 async function rollbackDatasource(dataplaneUrl, sourceIdOrKey, authConfig, rollbackData) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/rollback`, { body: rollbackData });
 }
 /** @requiresPermission {Dataplane} external-system:read */
 async function testDatasource(dataplaneUrl, sourceIdOrKey, authConfig, testData = {}) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/test`, { body: testData });
 }
 /** @requiresPermission {Dataplane} external-system:read */
 async function listDatasourceOpenAPIEndpoints(dataplaneUrl, sourceIdOrKey, authConfig, options = {}) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/openapi-endpoints`, { params: options });
 }
 /** @requiresPermission {Dataplane} audit:read or external-system:read */
 async function listExecutionLogs(dataplaneUrl, sourceIdOrKey, authConfig, options = {}) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/executions`, { params: options });
 }
 /** @requiresPermission {Dataplane} audit:read or external-system:read */
 async function getExecutionLog(dataplaneUrl, sourceIdOrKey, executionId, authConfig) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/executions/${executionId}`);
 }
 /** @requiresPermission {Dataplane} audit:read */
 async function listAllExecutionLogs(dataplaneUrl, authConfig, options = {}) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.get('/api/v1/external/executions', { params: options });
 }
-/** @requiresPermission {Dataplane} external-system:update */
+/**
+ * @deprecated Prefer {@link module:lib/api/records-bulk.api.bulkSyncRecords}.
+ * @requiresPermission {Dataplane} external-data-source:sync
+ */
 async function bulkOperation(dataplaneUrl, sourceIdOrKey, authConfig, bulkData) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
-  return await client.post(`/api/v1/external/${sourceIdOrKey}/bulk`, { body: bulkData });
+  const { bulkSyncRecords } = require('./records-bulk.api');
+  return await bulkSyncRecords(dataplaneUrl, sourceIdOrKey, authConfig, bulkData);
 }
 /** @requiresPermission {Dataplane} external-system:read */
 async function getDatasourceStatus(dataplaneUrl, sourceIdOrKey, authConfig) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/status`);
 }
 

package/lib/api/datasources-extended.api.js

@@ -4,107 +4,107 @@
  * @version 2.0.0
  */
 
-const { ApiClient } = require('./index');
+const { createDataplaneApiClient } = require('./index');
 
 /** @requiresPermission {Dataplane} external-system:read (records) */
 async function listRecords(dataplaneUrl, sourceIdOrKey, authConfig, options = {}) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/records`, { params: options });
 }
 /** @requiresPermission {Dataplane} external-system:create */
 async function createRecord(dataplaneUrl, sourceIdOrKey, authConfig, recordData) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/records`, { body: recordData });
 }
 /** @requiresPermission {Dataplane} external-system:read */
 async function getRecord(dataplaneUrl, sourceIdOrKey, recordIdOrKey, authConfig) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/records/${recordIdOrKey}`);
 }
 /** @requiresPermission {Dataplane} external-system:update */
 async function updateRecord(dataplaneUrl, sourceIdOrKey, recordIdOrKey, authConfig, updateData) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.put(`/api/v1/external/${sourceIdOrKey}/records/${recordIdOrKey}`, { body: updateData });
 }
 /** @requiresPermission {Dataplane} external-system:delete */
 async function deleteRecord(dataplaneUrl, sourceIdOrKey, recordIdOrKey, authConfig) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.delete(`/api/v1/external/${sourceIdOrKey}/records/${recordIdOrKey}`);
 }
 /** @requiresPermission {Dataplane} external-system:read (grants) */
 async function listGrants(dataplaneUrl, sourceIdOrKey, authConfig, options = {}) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/grants`, { params: options });
 }
 /** @requiresPermission {Dataplane} external-system:update */
 async function createGrant(dataplaneUrl, sourceIdOrKey, authConfig, grantData) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/grants`, { body: grantData });
 }
 /** @requiresPermission {Dataplane} external-system:read */
 async function getGrant(dataplaneUrl, sourceIdOrKey, grantIdOrKey, authConfig) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/grants/${grantIdOrKey}`);
 }
 /** @requiresPermission {Dataplane} external-system:update */
 async function updateGrant(dataplaneUrl, sourceIdOrKey, grantIdOrKey, authConfig, updateData) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.put(`/api/v1/external/${sourceIdOrKey}/grants/${grantIdOrKey}`, { body: updateData });
 }
 async function deleteGrant(dataplaneUrl, sourceIdOrKey, grantIdOrKey, authConfig) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.delete(`/api/v1/external/${sourceIdOrKey}/grants/${grantIdOrKey}`);
 }
 /** @requiresPermission {Dataplane} external-system:read (policies) */
 async function listPolicies(dataplaneUrl, sourceIdOrKey, authConfig, options = {}) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/policies`, { params: options });
 }
 /** @requiresPermission {Dataplane} external-system:update */
 async function attachPolicy(dataplaneUrl, sourceIdOrKey, authConfig, policyData) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/policies`, { body: policyData });
 }
 async function detachPolicy(dataplaneUrl, sourceIdOrKey, policyIdOrKey, authConfig) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.delete(`/api/v1/external/${sourceIdOrKey}/policies/${policyIdOrKey}`);
 }
 /** @requiresPermission {Dataplane} external-system:read (sync) */
 async function listSyncJobs(dataplaneUrl, sourceIdOrKey, authConfig, options = {}) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/sync`, { params: options });
 }
 async function createSyncJob(dataplaneUrl, sourceIdOrKey, authConfig, syncData) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/sync`, { body: syncData });
 }
 /** @requiresPermission {Dataplane} external-system:read */
 async function getSyncJob(dataplaneUrl, sourceIdOrKey, syncJobId, authConfig) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/sync/${syncJobId}`);
 }
 /** @requiresPermission {Dataplane} external-system:update */
 async function updateSyncJob(dataplaneUrl, sourceIdOrKey, syncJobId, authConfig, updateData) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.put(`/api/v1/external/${sourceIdOrKey}/sync/${syncJobId}`, { body: updateData });
 }
 async function executeSyncJob(dataplaneUrl, sourceIdOrKey, syncJobId, authConfig) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/sync/${syncJobId}/execute`);
 }
 /** @requiresPermission {Dataplane} document-record or external-system scope */
 async function validateDocuments(dataplaneUrl, sourceIdOrKey, authConfig, validateData) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/data-sources/${sourceIdOrKey}/documents/validate`, { body: validateData });
 }
 /** @requiresPermission {Dataplane} document-record or external-system scope */
 async function bulkDocuments(dataplaneUrl, sourceIdOrKey, authConfig, bulkData) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/data-sources/${sourceIdOrKey}/documents/bulk`, { body: bulkData });
 }
 /** @requiresPermission {Dataplane} document-record:read or external-system:read */
 async function listDocuments(dataplaneUrl, sourceIdOrKey, authConfig, options = {}) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/data-sources/${sourceIdOrKey}/documents`, { params: options });
 }
 

package/lib/api/dimensions.api.js

@@ -68,6 +68,9 @@ async function createDimension(controllerUrl, authConfig, body) {
     displayName: body.displayName,
     dataType: body.dataType
   };
+  if (body.valueType !== undefined && body.valueType !== null && body.valueType !== '') {
+    payload.valueType = body.valueType;
+  }
   if (body.description !== undefined && body.description !== null && body.description !== '') {
     payload.description = body.description;
   }

package/lib/api/external-systems.api.js

@@ -4,7 +4,7 @@
  * @version 2.0.0
  */
 
-const { ApiClient } = require('./index');
+const { createDataplaneApiClient } = require('./index');
 
 /**
  * List external systems
@@ -24,7 +24,7 @@ const { ApiClient } = require('./index');
  * @throws {Error} If request fails
  */
 async function listExternalSystems(dataplaneUrl, authConfig, options = {}) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.get('/api/v1/external/systems', {
     params: options
   });
@@ -43,7 +43,7 @@ async function listExternalSystems(dataplaneUrl, authConfig, options = {}) {
  * @throws {Error} If creation fails
  */
 async function createExternalSystem(dataplaneUrl, authConfig, systemData) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post('/api/v1/external/systems', {
     body: systemData
   });
@@ -66,7 +66,7 @@ async function createExternalSystem(dataplaneUrl, authConfig, systemData) {
  * @throws {Error} If request fails
  */
 async function getExternalSystem(dataplaneUrl, systemIdOrKey, authConfig) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/systems/${systemIdOrKey}`);
 }
 
@@ -84,7 +84,7 @@ async function getExternalSystem(dataplaneUrl, systemIdOrKey, authConfig) {
  * @throws {Error} If update fails
  */
 async function updateExternalSystem(dataplaneUrl, systemIdOrKey, authConfig, updateData) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.put(`/api/v1/external/systems/${systemIdOrKey}`, {
     body: updateData
   });
@@ -103,7 +103,7 @@ async function updateExternalSystem(dataplaneUrl, systemIdOrKey, authConfig, upd
  * @throws {Error} If deletion fails
  */
 async function deleteExternalSystem(dataplaneUrl, systemIdOrKey, authConfig) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.delete(`/api/v1/external/systems/${systemIdOrKey}`);
 }
 
@@ -120,7 +120,7 @@ async function deleteExternalSystem(dataplaneUrl, systemIdOrKey, authConfig) {
  * @throws {Error} If request fails
  */
 async function getExternalSystemConfig(dataplaneUrl, systemIdOrKey, authConfig) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/systems/${systemIdOrKey}/config`);
 }
 
@@ -140,7 +140,7 @@ async function getExternalSystemConfig(dataplaneUrl, systemIdOrKey, authConfig)
  * @throws {Error} If creation fails
  */
 async function createFromTemplate(dataplaneUrl, authConfig, templateData) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post('/api/v1/external/systems/from-template', {
     body: templateData
   });
@@ -160,7 +160,7 @@ async function createFromTemplate(dataplaneUrl, authConfig, templateData) {
  * @throws {Error} If request fails
  */
 async function listOpenAPIFiles(dataplaneUrl, systemIdOrKey, authConfig, options = {}) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/systems/${systemIdOrKey}/openapi-files`, {
     params: options
   });
@@ -180,7 +180,7 @@ async function listOpenAPIFiles(dataplaneUrl, systemIdOrKey, authConfig, options
  * @throws {Error} If request fails
  */
 async function listOpenAPIEndpoints(dataplaneUrl, systemIdOrKey, authConfig, options = {}) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/systems/${systemIdOrKey}/openapi-endpoints`, {
     params: options
   });
@@ -201,7 +201,7 @@ async function listOpenAPIEndpoints(dataplaneUrl, systemIdOrKey, authConfig, opt
  * @throws {Error} If publish fails
  */
 async function publishExternalSystem(dataplaneUrl, systemIdOrKey, authConfig, publishData = {}) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/systems/${systemIdOrKey}/publish`, {
     body: publishData
   });
@@ -222,7 +222,7 @@ async function publishExternalSystem(dataplaneUrl, systemIdOrKey, authConfig, pu
  * @throws {Error} If rollback fails
  */
 async function rollbackExternalSystem(dataplaneUrl, systemIdOrKey, authConfig, rollbackData) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/systems/${systemIdOrKey}/rollback`, {
     body: rollbackData
   });
@@ -244,7 +244,7 @@ async function rollbackExternalSystem(dataplaneUrl, systemIdOrKey, authConfig, r
  * @throws {Error} If save fails
  */
 async function saveAsTemplate(dataplaneUrl, systemIdOrKey, authConfig, templateData) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/systems/${systemIdOrKey}/save-template`, {
     body: templateData
   });

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

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Dataplane governance scenario acceptance API
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+const { createDataplaneApiClient } = require('./index');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+
+/**
+ * Run governance scenario pack (ABAC visibility proof).
+ * POST /api/v1/governance/scenarios/run
+ * @requiresPermission {Dataplane} governance:evaluate
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {import('./types/governance-scenarios.types').GovernanceScenariosRunRequest} body
+ * @returns {Promise<import('./types/governance-scenarios.types').GovernanceScenariosRunResponse>}
+ */
+async function runGovernanceScenarios(dataplaneUrl, authConfig, body) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.post('/api/v1/governance/scenarios/run', { body });
+  if (res && res.success === false) {
+    const msg =
+      (res.error && (res.error.formattedError || res.error.error || res.error.message)) ||
+      res.formattedError ||
+      'Governance scenario run failed';
+    throw new Error(msg);
+  }
+  const unwrapped = unwrapApiData(res);
+  if (!unwrapped || !unwrapped.summary) {
+    throw new Error('Governance scenario run returned an unexpected response shape');
+  }
+  return unwrapped;
+}
+
+module.exports = {
+  runGovernanceScenarios
+};

package/lib/api/groups.api.js

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview Groups API (Controller /api/v1/groups)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { ApiClient } = require('./index');
+
+const BASE = '/api/v1/groups';
+
+/**
+ * List groups (paginated)
+ * @requiresPermission {Controller} groups:read
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {Object} [options]
+ * @returns {Promise<Object>}
+ */
+async function listGroups(controllerUrl, authConfig, options = {}) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.get(BASE, { params: options });
+}
+
+/**
+ * Get group by id or name
+ * @requiresPermission {Controller} groups:read
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {string} groupIdOrName
+ * @param {Object} [options]
+ * @returns {Promise<Object>}
+ */
+async function getGroup(controllerUrl, authConfig, groupIdOrName, options = {}) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  const params = {};
+  if (options.includeMembers) {
+    params.includeMembers = 'true';
+  }
+  return await client.get(`${BASE}/${encodeURIComponent(groupIdOrName)}`, { params });
+}
+
+/**
+ * Create group
+ * @requiresPermission {Controller} groups:create
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {Object} body
+ * @returns {Promise<Object>}
+ */
+async function createGroup(controllerUrl, authConfig, body) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.post(BASE, { body });
+}
+
+/**
+ * List group members
+ * @requiresPermission {Controller} groups:read
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {string} groupIdOrName
+ * @returns {Promise<Object>}
+ */
+async function listGroupMembers(controllerUrl, authConfig, groupIdOrName) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.get(`${BASE}/${encodeURIComponent(groupIdOrName)}/members`);
+}
+
+module.exports = {
+  listGroups,
+  getGroup,
+  createGroup,
+  listGroupMembers
+};