@aifabrix/builder 2.45.0 → 2.45.5

package/.cursor/rules/docs-rules.mdc

@@ -5,10 +5,12 @@ alwaysApply: true
 
 ## Audience
 
-Documents under **docs/** (including **docs/commands/**) are **CLI developer / user documentation**. The audience is people who use the AI Fabrix Builder CLI or integrate it into workflows. They do not need to know how the CLI talks to the Controller or Dataplane over HTTP.
+Documents under **docs/** (including **docs/commands/**) are **public CLI user documentation**. The audience is people who use the AI Fabrix Builder CLI or integrate it into workflows—they may **not** have access to private monorepos (dataplane, miso-controller, internal plans). They do not need to know how the CLI talks to the Controller or Dataplane over HTTP.
 
 ## Do Not Include in CLI User Docs
 
+- **Links or paths into other product repos (FORBIDDEN)** – No markdown links, examples, or prerequisites that point at private/sibling repositories or their trees: `../../../aifabrix-dataplane/...`, `../../aifabrix-miso/...`, `packages/miso-controller/...`, `integration/<fixture>/README.md` in another repo, `.cursor/plans/` anywhere, `/workspace/...` monorepo layouts, or “see the dataplane/miso-controller repo”. **Only** cross-link within **`docs/`** and use on-disk paths the user owns (`integration/<systemKey>/...`, `builder/<appKey>/...`, `~/.aifabrix/...`).
+- **Internal plan or ticket IDs** – No “Plan 407.1”, “plan section 2.3”, or similar; describe behavior in user terms.
 - **REST API details** – No HTTP methods, URL paths, or endpoint names (e.g. `GET /api/v1/...`, `POST .../pipeline/upload`).
 - **Request/response shapes** – No payload structures, status codes, or field names from backend APIs.
 - **Backend implementation terms** – Avoid referring to “pipeline config endpoint”, “upload endpoint”, or similar; describe what the **command** does from the user’s perspective.

package/integration/hubspot-test/test-artifacts/wizard-hubspot-credential-real.yaml

@@ -2,7 +2,7 @@ appName: wizard-e2e-credential-real
 mode: create-system
 source:
   type: openapi-file
-  filePath: /workspace/aifabrix-builder/integration/hubspot-test/companies.json
+  filePath: ./integration/hubspot-test/companies.json
 credential:
   action: create
   config:

package/integration/hubspot-test/test-artifacts/wizard-hubspot-env-vars.yaml

@@ -2,7 +2,7 @@ appName: wizard-e2e-env-vars
 mode: create-system
 source:
   type: openapi-file
-  filePath: /workspace/aifabrix-builder/integration/hubspot-test/companies.json
+  filePath: ./integration/hubspot-test/companies.json
 deployment:
   controller: ${CONTROLLER_URL}
   dataplane: ${DATAPLANE_URL}

package/integration/hubspot-test/wizard-hubspot-e2e.yaml

@@ -2,7 +2,7 @@ appName: wizard-e2e-e2e
 mode: create-system
 source:
   type: openapi-file
-  filePath: /workspace/aifabrix-builder/integration/hubspot-test/companies.json
+  filePath: ./integration/hubspot-test/companies.json
 credential:
   action: skip
 preferences:

package/jest.projects.js

@@ -278,7 +278,35 @@ const defaultProject = {
       '/tests/lib/datasource/run-capability-remove.test.js',
       '\\\\tests\\\\lib\\\\datasource\\\\run-capability-remove.test.js',
       'lib/datasource/run-capability-remove.test.js',
-      'run-capability-remove\\.test\\.js'
+      'run-capability-remove\\.test\\.js',
+      '/tests/lib/datasource/log-cleaner.test.js',
+      '\\\\tests\\\\lib\\\\datasource\\\\log-cleaner.test.js',
+      'lib/datasource/log-cleaner.test.js',
+      'log-cleaner\\.test\\.js',
+      '/tests/lib/datasource/datasource-exporter-service.test.js',
+      '\\\\tests\\\\lib\\\\datasource\\\\datasource-exporter-service.test.js',
+      'lib/datasource/datasource-exporter-service.test.js',
+      'datasource-exporter-service\\.test\\.js',
+      '/tests/lib/protection/paths.test.js',
+      '\\\\tests\\\\lib\\\\protection\\\\paths.test.js',
+      'lib/protection/paths.test.js',
+      'protection/paths\\.test\\.js',
+      '/tests/lib/protection/protection-resolve.test.js',
+      '\\\\tests\\\\lib\\\\protection\\\\protection-resolve.test.js',
+      'lib/protection/protection-resolve.test.js',
+      'protection-resolve\\.test\\.js',
+      '/tests/lib/protection/run-protection-create-helpers.test.js',
+      '\\\\tests\\\\lib\\\\protection\\\\run-protection-create-helpers.test.js',
+      'lib/protection/run-protection-create-helpers.test.js',
+      'run-protection-create-helpers\\.test\\.js',
+      '/tests/lib/governance/governance-pack-loader.test.js',
+      '\\\\tests\\\\lib\\\\governance\\\\governance-pack-loader.test.js',
+      'lib/governance/governance-pack-loader.test.js',
+      'governance-pack-loader\\.test\\.js',
+      '/tests/lib/protection/validate-batch.test.js',
+      '\\\\tests\\\\lib\\\\protection\\\\validate-batch.test.js',
+      'lib/protection/validate-batch.test.js',
+      'validate-batch\\.test\\.js'
     ];
     if (process.env.INCLUDE_LOCAL_TESTS !== 'true') {
       patterns.push('/tests/local/');
@@ -404,6 +432,21 @@ const isolatedProjects = [
     '**/tests/lib/datasource/run-capability-diff.test.js',
     '**/tests/lib/datasource/run-capability-edit.test.js',
     '**/tests/lib/datasource/run-capability-remove.test.js'
+  ]),
+  makeIsolatedProject('log-cleaner', ['**/tests/lib/datasource/log-cleaner.test.js']),
+  makeIsolatedProject('datasource-exporter-service', [
+    '**/tests/lib/datasource/datasource-exporter-service.test.js'
+  ]),
+  makeIsolatedProject('protection-paths', ['**/tests/lib/protection/paths.test.js']),
+  makeIsolatedProject('protection-resolve', ['**/tests/lib/protection/protection-resolve.test.js']),
+  makeIsolatedProject('protection-create-helpers', [
+    '**/tests/lib/protection/run-protection-create-helpers.test.js'
+  ]),
+  makeIsolatedProject('governance-pack-loader', [
+    '**/tests/lib/governance/governance-pack-loader.test.js'
+  ]),
+  makeIsolatedProject('protection-validate-batch', [
+    '**/tests/lib/protection/validate-batch.test.js'
   ])
 ];
 

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

@@ -0,0 +1,93 @@
+/**
+ * @fileoverview Agent metadata validation API (dataplane 404.5)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+const { createDataplaneApiClient } = require('./index');
+
+/**
+ * Run agent metadata validation for a datasource.
+ * POST /api/v1/external/{sourceIdOrKey}/agent-metadata-validation
+ * @requiresPermission {Dataplane} external-data-source:update
+ * @async
+ * @function runAgentMetadataValidation
+ * @param {string} dataplaneUrl - Dataplane base URL
+ * @param {string} sourceIdOrKey - Datasource key or ID
+ * @param {Object} authConfig - Authentication configuration
+ * @param {import('./types/agent-metadata-validation.types').AgentMetadataValidationRunRequest} [body]
+ * @returns {Promise<import('./types/agent-metadata-validation.types').AgentMetadataValidationRunResponse>}
+ */
+async function runAgentMetadataValidation(
+  dataplaneUrl,
+  sourceIdOrKey,
+  authConfig,
+  body = {},
+  opts = {}
+) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const requestOpts = { body };
+  if (opts.timeoutMs !== undefined && opts.timeoutMs !== null) {
+    requestOpts.timeoutMs = opts.timeoutMs;
+  }
+  return await client.post(
+    `/api/v1/external/${encodeURIComponent(sourceIdOrKey)}/agent-metadata-validation`,
+    requestOpts
+  );
+}
+
+/**
+ * Get latest agent metadata validation result.
+ * GET /api/v1/external/{sourceIdOrKey}/agent-validation
+ * @requiresPermission {Dataplane} external-data-source:read
+ * @async
+ * @function getLatestAgentMetadataValidation
+ * @param {string} dataplaneUrl - Dataplane base URL
+ * @param {string} sourceIdOrKey - Datasource key or ID
+ * @param {Object} authConfig - Authentication configuration
+ * @returns {Promise<import('./types/agent-metadata-validation.types').AgentMetadataValidationResult>}
+ */
+async function getLatestAgentMetadataValidation(
+  dataplaneUrl,
+  sourceIdOrKey,
+  authConfig,
+  opts = {}
+) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const requestOpts = {};
+  if (opts.timeoutMs !== undefined && opts.timeoutMs !== null) {
+    requestOpts.timeoutMs = opts.timeoutMs;
+  }
+  return await client.get(
+    `/api/v1/external/${encodeURIComponent(sourceIdOrKey)}/agent-validation`,
+    requestOpts
+  );
+}
+
+/**
+ * List agent metadata validation history.
+ * GET /api/v1/external/{sourceIdOrKey}/agent-validation/history
+ * @requiresPermission {Dataplane} external-data-source:read
+ * @async
+ * @function listAgentMetadataValidationHistory
+ * @param {string} dataplaneUrl - Dataplane base URL
+ * @param {string} sourceIdOrKey - Datasource key or ID
+ * @param {Object} authConfig - Authentication configuration
+ * @returns {Promise<import('./types/agent-metadata-validation.types').AgentMetadataValidationHistoryItem[]>}
+ */
+async function listAgentMetadataValidationHistory(
+  dataplaneUrl,
+  sourceIdOrKey,
+  authConfig
+) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  return await client.get(
+    `/api/v1/external/${encodeURIComponent(sourceIdOrKey)}/agent-validation/history`
+  );
+}
+
+module.exports = {
+  runAgentMetadataValidation,
+  getLatestAgentMetadataValidation,
+  listAgentMetadataValidationHistory
+};

package/lib/api/audit-api-helpers.js

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview Shared helpers for dataplane audit API responses
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+
+/**
+ * @param {*} res
+ * @throws {Error}
+ */
+function assertAuditApiSuccess(res) {
+  if (!res || typeof res !== 'object') {
+    throw new Error('Audit API returned an empty response');
+  }
+  if (res.success === false) {
+    const msg =
+      (res.error && (res.error.formattedError || res.error.error || res.error.message)) ||
+      res.formattedError ||
+      'Audit API request failed';
+    const err = new Error(msg);
+    if (res.status) err.status = res.status;
+    throw err;
+  }
+}
+
+/**
+ * @param {*} res
+ * @returns {{ data: Array, meta: Object|null, raw: Object|null }}
+ */
+function unwrapPaginatedAuditList(res) {
+  assertAuditApiSuccess(res);
+  const body = unwrapApiData(res);
+  if (!body || typeof body !== 'object') {
+    return { data: [], meta: null, raw: null };
+  }
+  const data = Array.isArray(body.data)
+    ? body.data
+    : Array.isArray(body.items)
+      ? body.items
+      : [];
+  const meta = body.meta && typeof body.meta === 'object' ? body.meta : null;
+  return { data, meta, raw: body };
+}
+
+/**
+ * Unwrap execution sub-resource envelope `{ root: T }`.
+ * @param {*} res
+ * @returns {*|null}
+ */
+function unwrapExecutionSubresource(res) {
+  assertAuditApiSuccess(res);
+  const body = unwrapApiData(res);
+  if (body === null || body === undefined) return null;
+  if (typeof body === 'object' && Object.prototype.hasOwnProperty.call(body, 'root')) {
+    return body.root;
+  }
+  return body;
+}
+
+module.exports = {
+  assertAuditApiSuccess,
+  unwrapPaginatedAuditList,
+  unwrapExecutionSubresource
+};

package/lib/api/audit.api.js

@@ -0,0 +1,119 @@
+/**
+ * @fileoverview Dataplane audit read API (Plan 407.1 / 407.3 evidence matrix)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { createDataplaneApiClient } = require('./index');
+const { unwrapPaginatedAuditList, unwrapExecutionSubresource } = require('./audit-api-helpers');
+
+const AUDIT_BASE = '/api/v1/audit';
+const DEFAULT_PAGE_SIZE = 100;
+
+/**
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {Object} [query]
+ * @returns {Promise<{ data: import('./types/audit.types').AuditExecutionListItem[], meta: import('./types/audit.types').AuditListMeta|null }>}
+ * @requiresPermission {Dataplane} audit:read
+ */
+async function queryExecutions(dataplaneUrl, authConfig, query = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(`${AUDIT_BASE}/executions`, {
+    params: {
+      page: 1,
+      pageSize: DEFAULT_PAGE_SIZE,
+      ...query
+    }
+  });
+  return unwrapPaginatedAuditList(res);
+}
+
+/**
+ * @requiresPermission {Dataplane} audit:read
+ */
+async function queryRbacDecisions(dataplaneUrl, authConfig, query = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(`${AUDIT_BASE}/rbac-decisions`, {
+    params: {
+      page: 1,
+      pageSize: DEFAULT_PAGE_SIZE,
+      sort: '-timestamp',
+      ...query
+    }
+  });
+  return unwrapPaginatedAuditList(res);
+}
+
+/**
+ * @requiresPermission {Dataplane} audit:read
+ */
+async function queryAbacTraces(dataplaneUrl, authConfig, query = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(`${AUDIT_BASE}/abac-traces`, {
+    params: {
+      page: 1,
+      pageSize: DEFAULT_PAGE_SIZE,
+      ...query
+    }
+  });
+  return unwrapPaginatedAuditList(res);
+}
+
+/**
+ * @requiresPermission {Dataplane} audit:read
+ */
+async function getExecutionRbac(dataplaneUrl, authConfig, executionId) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(`${AUDIT_BASE}/executions/${executionId}/rbac`);
+  return unwrapExecutionSubresource(res);
+}
+
+/**
+ * @requiresPermission {Dataplane} audit:read
+ */
+async function getExecutionAbac(dataplaneUrl, authConfig, executionId) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(`${AUDIT_BASE}/executions/${executionId}/abac`);
+  return unwrapExecutionSubresource(res);
+}
+
+/**
+ * @requiresPermission {Dataplane} audit:read
+ */
+async function getExecutionTrace(dataplaneUrl, authConfig, executionId) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(`${AUDIT_BASE}/executions/${executionId}/trace`);
+  return unwrapExecutionSubresource(res);
+}
+
+/**
+ * @requiresPermission {Dataplane} audit:read
+ */
+async function getExecutionSteps(dataplaneUrl, authConfig, executionId) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(`${AUDIT_BASE}/executions/${executionId}/steps`);
+  return unwrapExecutionSubresource(res);
+}
+
+/**
+ * @requiresPermission {Dataplane} audit:read
+ */
+async function getExecutionErrors(dataplaneUrl, authConfig, executionId) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(`${AUDIT_BASE}/executions/${executionId}/errors`);
+  return unwrapExecutionSubresource(res);
+}
+
+module.exports = {
+  queryExecutions,
+  queryRbacDecisions,
+  queryAbacTraces,
+  getExecutionRbac,
+  getExecutionAbac,
+  getExecutionTrace,
+  getExecutionSteps,
+  getExecutionErrors
+};

package/lib/api/auth-cache.api.js

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview Controller auth/RBAC cache API
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { ApiClient } = require('./index');
+
+const CLEAR_PATH = '/api/v1/auth/cache/clear';
+const INVALIDATE_PATH = '/api/v1/auth/cache/invalidate';
+
+/**
+ * Clear all controller cache entries
+ * @requiresPermission {Controller} cache:admin
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @returns {Promise<Object>}
+ */
+async function clearAuthCache(controllerUrl, authConfig) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.post(CLEAR_PATH);
+}
+
+/**
+ * Invalidate cache entries matching a pattern
+ * @requiresPermission {Controller} cache:admin
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {string} pattern
+ * @returns {Promise<Object>}
+ */
+async function invalidateAuthCache(controllerUrl, authConfig, pattern) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.post(INVALIDATE_PATH, { body: { pattern } });
+}
+
+module.exports = {
+  clearAuthCache,
+  invalidateAuthCache
+};

package/lib/api/certificates.api.js

@@ -4,7 +4,7 @@
  * @version 2.0.0
  */
 
-const { ApiClient } = require('./index');
+const { createDataplaneApiClient } = require('./index');
 const { normalizeDataplaneAuth } = require('./validation-run.api');
 
 /**
@@ -36,7 +36,7 @@ function dataplaneAuthForBearerGet(authConfig) {
  * @returns {Promise<Object>} API envelope `{ success, data?, status, ... }`
  */
 async function getActiveIntegrationCertificate(dataplaneUrl, authConfig, systemKey, datasourceKey) {
-  const client = new ApiClient(dataplaneUrl, dataplaneAuthForBearerGet(authConfig));
+  const client = createDataplaneApiClient(dataplaneUrl, dataplaneAuthForBearerGet(authConfig));
   const path = `/api/v1/systems/${encodeURIComponent(systemKey)}/datasources/${encodeURIComponent(
     datasourceKey
   )}/certificates/active`;
@@ -54,7 +54,7 @@ async function getActiveIntegrationCertificate(dataplaneUrl, authConfig, systemK
  * @returns {Promise<Object>}
  */
 async function listIntegrationCertificates(dataplaneUrl, authConfig, params = {}) {
-  const client = new ApiClient(dataplaneUrl, dataplaneAuthForBearerGet(authConfig));
+  const client = createDataplaneApiClient(dataplaneUrl, dataplaneAuthForBearerGet(authConfig));
   return await client.get('/api/v1/certificates', { params });
 }
 
@@ -69,7 +69,7 @@ async function listIntegrationCertificates(dataplaneUrl, authConfig, params = {}
  * @returns {Promise<Object>}
  */
 async function verifyIntegrationCertificate(dataplaneUrl, authConfig, body) {
-  const client = new ApiClient(dataplaneUrl, dataplaneAuthForBearerGet(authConfig));
+  const client = createDataplaneApiClient(dataplaneUrl, dataplaneAuthForBearerGet(authConfig));
   return await client.post('/api/v1/certificates/verify', { body: body || {} });
 }
 

package/lib/api/credential.api.js

@@ -4,7 +4,7 @@
  * @version 2.0.0
  */
 
-const { ApiClient } = require('./index');
+const { createDataplaneApiClient } = require('./index');
 
 const CREDENTIAL_SECRET_ENDPOINT = '/api/v1/credential/secret';
 
@@ -29,7 +29,7 @@ async function storeCredentialSecrets(dataplaneUrl, authConfig, items) {
   if (!items || !Array.isArray(items) || items.length === 0) {
     return { stored: 0 };
   }
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.post(CREDENTIAL_SECRET_ENDPOINT, {
     body: items
   });

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