@aifabrix/builder 2.45.0 → 2.46.0

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

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

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

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

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

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

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

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

package/lib/api/types/protection.types.js

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview Protection API type definitions (dataplane /api/v1/protection/*).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+/**
+ * @typedef {Object} ProtectionUploadRequest
+ * @property {Object} manifest - Full protection manifest document
+ */
+
+/**
+ * @typedef {Object} ProtectionValidateOptions
+ * @property {boolean} [strict] - Promote WARN to FAIL
+ * @property {boolean} [explain]
+ * @property {number} [sampleSize] - For simulate
+ */
+
+/**
+ * @typedef {Object} ProtectionDeployResponse
+ * @property {string} protectionKey
+ * @property {string} deploymentId
+ * @property {number} revision
+ * @property {string} configHash
+ * @property {string} deployedAt
+ * @property {Object} manifest
+ */
+
+/**
+ * @typedef {Object} ProtectionManifestResponse
+ * @property {string} key
+ * @property {string} displayName
+ * @property {Object} spec
+ * @property {boolean} enabled
+ * @property {string} datasourceKey
+ * @property {number} [currentRevision]
+ * @property {string} [lastDeployedAt]
+ */
+
+/**
+ * @typedef {Object} ProtectionListResult
+ * @property {ProtectionManifestResponse[]} items
+ * @property {Object|null} meta
+ * @property {*} raw
+ */
+
+/**
+ * @typedef {Object} ProtectionGrantStatusSummary
+ * @property {string} dimensionKey
+ * @property {string} effectiveValueType
+ * @property {string} projectionRuleKey
+ */
+
+/**
+ * @typedef {Object} ProtectionStatusResponse
+ * @property {string} protectionKey
+ * @property {boolean} enabled
+ * @property {string} datasourceKey
+ * @property {number} [currentRevision]
+ * @property {string} [configHash]
+ * @property {string} [lastDeployedAt]
+ * @property {string} [lastProjectionRunAt]
+ * @property {string} [lastSuccessfulProjectionRunAt]
+ * @property {number} [dynamicValueCount]
+ * @property {number} [grantCount]
+ * @property {ProtectionGrantStatusSummary[]} [grants]
+ */
+
+module.exports = {};

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

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview Types for dataplane bulk record sync API
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+/**
+ * Single record in a bulk sync request
+ * @typedef {Object} ExternalBulkRecord
+ * @property {string} key - External record key
+ * @property {string} displayName - Human-readable label
+ * @property {string} recordType - Resource type from datasource manifest
+ * @property {Object} metadata - Record metadata payload
+ */
+
+/**
+ * Bulk sync request body
+ * @typedef {Object} ExternalRecordBulkRequest
+ * @property {'incremental'|'bulk'|'validate'} syncType - Sync mode
+ * @property {boolean} [sync] - Create linked sync job when true
+ * @property {ExternalBulkRecord[]} records - Records to process
+ */
+
+/**
+ * Bulk sync response
+ * @typedef {Object} ExternalRecordBulkResponse
+ * @property {number} insertedCount
+ * @property {number} updatedCount
+ * @property {number} deletedCount
+ * @property {number} totalProcessed
+ * @property {number} [skippedCount]
+ * @property {Object} [recordSkipSummary]
+ */
+
+module.exports = {};

package/lib/api/types/records-search.types.js

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Types for dataplane Records Search API
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+/**
+ * Records search request
+ * @typedef {Object} RecordsSearchRequest
+ * @property {'retrieval'|'grounding'|'analytics'|'validation'} intent
+ * @property {string[]} [datasourceKeys]
+ * @property {string[]} [resourceTypes]
+ * @property {string|Object} [filters]
+ * @property {string|Object} [exclude]
+ * @property {'ids'|'full'} [searchMode]
+ * @property {number} [limit]
+ * @property {boolean} [dryRun]
+ */
+
+/**
+ * Records search response
+ * @typedef {Object} RecordsSearchResponse
+ * @property {Array<string|Object>} data
+ * @property {Object} meta
+ * @property {Object} [links]
+ */
+
+module.exports = {};

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

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview User–group membership API (Controller)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { ApiClient } = require('./index');
+
+/**
+ * Add user to group
+ * @requiresPermission {Controller} users:update
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {string} userId
+ * @param {string} groupId
+ * @param {Object} [body]
+ * @returns {Promise<Object>}
+ */
+async function addUserToGroup(controllerUrl, authConfig, userId, groupId, body = {}) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.post(
+    `/api/v1/users/${encodeURIComponent(userId)}/groups/${encodeURIComponent(groupId)}`,
+    { body }
+  );
+}
+
+/**
+ * Remove user from group
+ * @requiresPermission {Controller} users:update
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {string} userId
+ * @param {string} groupId
+ * @returns {Promise<Object>}
+ */
+async function removeUserFromGroup(controllerUrl, authConfig, userId, groupId) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.delete(
+    `/api/v1/users/${encodeURIComponent(userId)}/groups/${encodeURIComponent(groupId)}`
+  );
+}
+
+module.exports = {
+  addUserToGroup,
+  removeUserFromGroup
+};

package/lib/api/users.api.js

@@ -0,0 +1,95 @@
+/**
+ * @fileoverview Users API (Controller /api/v1/users)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { ApiClient } = require('./index');
+
+const BASE = '/api/v1/users';
+
+/**
+ * List users (paginated)
+ * @requiresPermission {Controller} users:read
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {Object} [options]
+ * @returns {Promise<Object>}
+ */
+async function listUsers(controllerUrl, authConfig, options = {}) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.get(BASE, { params: options });
+}
+
+/**
+ * Get user by id
+ * @requiresPermission {Controller} users:read
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {string} userId
+ * @param {Object} [options]
+ * @returns {Promise<Object>}
+ */
+async function getUser(controllerUrl, authConfig, userId, options = {}) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  const params = {};
+  if (options.includeGroups) {
+    params.includeGroups = 'true';
+  }
+  return await client.get(`${BASE}/${encodeURIComponent(userId)}`, { params });
+}
+
+/**
+ * Create user
+ * @requiresPermission {Controller} users:create
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {Object} body
+ * @returns {Promise<Object>}
+ */
+async function createUser(controllerUrl, authConfig, body) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.post(BASE, { body });
+}
+
+/**
+ * Patch user
+ * @requiresPermission {Controller} users:update
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {string} userId
+ * @param {Object} body
+ * @returns {Promise<Object>}
+ */
+async function updateUser(controllerUrl, authConfig, userId, body) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.patch(`${BASE}/${encodeURIComponent(userId)}`, { body });
+}
+
+/**
+ * List groups for a user
+ * @requiresPermission {Controller} users:read
+ * @async
+ * @param {string} controllerUrl
+ * @param {Object} authConfig
+ * @param {string} userId
+ * @returns {Promise<Object>}
+ */
+async function listUserGroups(controllerUrl, authConfig, userId) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.get(`${BASE}/${encodeURIComponent(userId)}/groups`);
+}
+
+module.exports = {
+  listUsers,
+  getUser,
+  createUser,
+  updateUser,
+  listUserGroups
+};

package/lib/api/validation-run.api.js

@@ -4,7 +4,7 @@
  * @version 2.0.0
  */
 
-const { ApiClient } = require('./index');
+const { createDataplaneApiClient } = require('./index');
 
 const POST_PATH = '/api/v1/validation/run';
 
@@ -52,7 +52,7 @@ function normalizeDataplaneAuth(authConfig) {
 async function postValidationRun(dataplaneUrl, authConfig, body, transportOpts = {}) {
   const hdrs = buildClientCredentialHeaders(authConfig);
   const clientAuth = hdrs ? {} : normalizeDataplaneAuth(authConfig);
-  const client = new ApiClient(dataplaneUrl, clientAuth);
+  const client = createDataplaneApiClient(dataplaneUrl, clientAuth);
   const postOpts = { body, headers: hdrs || undefined };
   if (Number.isFinite(transportOpts.timeoutMs) && transportOpts.timeoutMs > 0) {
     postOpts.timeoutMs = transportOpts.timeoutMs;
@@ -77,7 +77,7 @@ async function getValidationRun(dataplaneUrl, authConfig, testRunId, transportOp
   }
   const hdrs = buildClientCredentialHeaders(authConfig);
   const clientAuth = hdrs ? {} : normalizeDataplaneAuth(authConfig);
-  const client = new ApiClient(dataplaneUrl, clientAuth);
+  const client = createDataplaneApiClient(dataplaneUrl, clientAuth);
   const path = `${POST_PATH}/${encodeURIComponent(testRunId)}`;
   const getOpts = { headers: hdrs || undefined };
   if (Number.isFinite(transportOpts.timeoutMs) && transportOpts.timeoutMs > 0) {

package/lib/api/validation-runner.js

@@ -10,7 +10,6 @@ const { extractTestRunId } = require('./validation-run.api');
 const { postValidationRunWithTransportRetry } = require('../utils/validation-run-post-retry');
 const { pollValidationRunUntilComplete } = require('../utils/validation-run-poll');
 const { createValidationPollHandlers } = require('../utils/validation-poll-ui');
-const logger = require('../utils/logger');
 
 /**
  * POST /api/v1/validation/run and (when async) poll GET until reportCompleteness is full.
@@ -23,6 +22,7 @@ const logger = require('../utils/logger');
  * @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,8 +60,10 @@ async function postValidationRunAndOptionalPoll(opts) {
     const remaining = Math.max(0, timeoutMs - elapsed);
     const deadlineMs = Date.now() + remaining;
 
-    logger.log('');
-    const pollUi = createValidationPollHandlers(deadlineMs);
+    const pollUi = createValidationPollHandlers(deadlineMs, {
+      subject: opts.pollSubject,
+      quiet: opts.quietPollUi === true
+    });
     const mergeOnPollProgress =
       typeof opts.onPollProgress === 'function'
         ? (envelope, attemptIndex, meta) => {

package/lib/api/wizard-platform.api.js

@@ -4,7 +4,7 @@
  * @version 2.0.0
  */
 
-const { ApiClient } = require('./index');
+const { createDataplaneApiClient } = require('./index');
 
 /**
  * Get platform details including available datasources
@@ -19,7 +19,7 @@ const { ApiClient } = require('./index');
  * @throws {Error} If request fails or platform not found (404)
  */
 async function getPlatformDetails(dataplaneUrl, authConfig, platformKey) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   const response = await client.get(`/api/v1/wizard/platforms/${encodeURIComponent(platformKey)}`);
   if (!response.success) {
     const msg = response.status === 404
@@ -45,7 +45,7 @@ async function getPlatformDetails(dataplaneUrl, authConfig, platformKey) {
  * @throws {Error} If request fails
  */
 async function discoverEntities(dataplaneUrl, authConfig, openapiSpec) {
-  const client = new ApiClient(dataplaneUrl, authConfig);
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   const response = await client.post('/api/v1/wizard/discover-entities', {
     body: { openapiSpec }
   });