@aifabrix/builder 2.45.0 → 2.45.5

package/lib/api/protection.api.js

@@ -0,0 +1,157 @@
+/**
+ * @fileoverview Protection manifest API (dataplane /api/v1/protection/*).
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { createDataplaneApiClient } = require('./index');
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+
+const BASE = '/api/v1/protection';
+
+/**
+ * @param {*} res
+ * @returns {*}
+ */
+function unwrapBody(res) {
+  return unwrapApiData(res) ?? res;
+}
+
+/**
+ * POST /api/v1/protection/validate
+ * @requiresPermission {Dataplane} external-system:read
+ */
+async function validateProtection(dataplaneUrl, authConfig, manifest, opts = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const params = {};
+  if (opts.strict === true) params.strict = true;
+  if (opts.explain === true) params.explain = true;
+  const res = await client.post(`${BASE}/validate`, {
+    body: { manifest },
+    params
+  });
+  return unwrapBody(res);
+}
+
+/**
+ * POST /api/v1/protection/simulate
+ * @requiresPermission {Dataplane} external-system:read
+ */
+async function simulateProtection(dataplaneUrl, authConfig, manifest, opts = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const params = {};
+  if (opts.strict === true) params.strict = true;
+  if (opts.explain === true) params.explain = true;
+  if (opts.sampleSize !== undefined && opts.sampleSize !== null) {
+    params.sampleSize = opts.sampleSize;
+  }
+  const res = await client.post(`${BASE}/simulate`, {
+    body: { manifest },
+    params
+  });
+  return unwrapBody(res);
+}
+
+/**
+ * POST /api/v1/protection/upload
+ * @requiresPermission {Dataplane} external-system:publish
+ */
+async function uploadProtection(dataplaneUrl, authConfig, manifest) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.post(`${BASE}/upload`, { body: { manifest } });
+  return unwrapBody(res);
+}
+
+/**
+ * GET /api/v1/protection/{key}
+ * @requiresPermission {Dataplane} external-system:read
+ */
+async function getProtection(dataplaneUrl, authConfig, key) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(`${BASE}/${encodeURIComponent(key)}`);
+  return unwrapBody(res);
+}
+
+/**
+ * GET /api/v1/protection/{key}/status
+ * @requiresPermission {Dataplane} external-system:read
+ */
+async function getProtectionStatus(dataplaneUrl, authConfig, key) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(`${BASE}/${encodeURIComponent(key)}/status`);
+  return unwrapBody(res);
+}
+
+/**
+ * @param {*} body
+ * @returns {Object[]}
+ */
+function extractProtectionListItems(body) {
+  if (!body || typeof body !== 'object') {
+    return [];
+  }
+  if (Array.isArray(body.data)) {
+    return body.data;
+  }
+  if (Array.isArray(body.items)) {
+    return body.items;
+  }
+  if (Array.isArray(body)) {
+    return body;
+  }
+  return [];
+}
+
+/**
+ * GET /api/v1/protection
+ * @requiresPermission {Dataplane} external-system:read
+ * @returns {Promise<{ items: Object[], meta: Object|null, raw: * }>}
+ */
+async function listProtectionManifests(dataplaneUrl, authConfig, options = {}) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const res = await client.get(BASE, { params: options });
+  const body = unwrapBody(res);
+  return {
+    items: extractProtectionListItems(body),
+    meta: body && typeof body === 'object' && body.meta ? body.meta : null,
+    raw: body
+  };
+}
+
+/**
+ * DELETE /api/v1/protection/{key}
+ * @requiresPermission {Dataplane} external-system:delete
+ */
+async function deleteProtection(dataplaneUrl, authConfig, key) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  return await client.delete(`${BASE}/${encodeURIComponent(key)}`);
+}
+
+/**
+ * Find deployed protection key by datasource key (client-side scan).
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} datasourceKey
+ * @returns {Promise<string|null>}
+ */
+async function findProtectionKeyByDatasource(dataplaneUrl, authConfig, datasourceKey) {
+  const { items } = await listProtectionManifests(dataplaneUrl, authConfig, {
+    page: 1,
+    pageSize: 100
+  });
+  const match = items.find((row) => String(row?.datasourceKey || '').trim() === datasourceKey);
+  return match?.key ? String(match.key) : null;
+}
+
+module.exports = {
+  validateProtection,
+  simulateProtection,
+  uploadProtection,
+  getProtection,
+  getProtectionStatus,
+  listProtectionManifests,
+  deleteProtection,
+  findProtectionKeyByDatasource
+};

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

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Dataplane bulk record sync API (data-storage records/bulk)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+const { createDataplaneApiClient } = require('./index');
+
+/**
+ * Bulk sync external records for a datasource.
+ * POST /api/v1/data-storage/{sourceIdOrKey}/records/bulk
+ * @requiresPermission {Dataplane} external-data-source:sync
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {string} sourceIdOrKey
+ * @param {Object} authConfig
+ * @param {import('./types/records-bulk.types').ExternalRecordBulkRequest} body
+ * @returns {Promise<import('./types/records-bulk.types').ExternalRecordBulkResponse>}
+ */
+async function bulkSyncRecords(dataplaneUrl, sourceIdOrKey, authConfig, body) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  return await client.post(
+    `/api/v1/data-storage/${encodeURIComponent(sourceIdOrKey)}/records/bulk`,
+    { body }
+  );
+}
+
+module.exports = {
+  bulkSyncRecords
+};

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

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview Normalize dataplane Records Search client responses
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * Unwrap ApiClient `{ success, data: { data, meta, links } }` to a flat search result.
+ * @param {Object} response - Raw client.post result
+ * @returns {{ success: boolean, data: Array, meta: Object, links?: Object, status?: number, error?: string, formattedError?: string }}
+ */
+function normalizeRecordsSearchClientResponse(response) {
+  if (!response || response.success !== true) {
+    return response || { success: false, data: [], meta: {} };
+  }
+
+  const body = response.data;
+  if (body && typeof body === 'object' && Array.isArray(body.data)) {
+    return {
+      success: true,
+      data: body.data,
+      meta: body.meta && typeof body.meta === 'object' ? body.meta : {},
+      links: body.links,
+      status: response.status
+    };
+  }
+
+  if (Array.isArray(body)) {
+    return {
+      success: true,
+      data: body,
+      meta: response.meta && typeof response.meta === 'object' ? response.meta : {},
+      status: response.status
+    };
+  }
+
+  return {
+    success: true,
+    data: [],
+    meta: body && typeof body === 'object' && body.meta ? body.meta : {},
+    status: response.status
+  };
+}
+
+module.exports = {
+  normalizeRecordsSearchClientResponse
+};

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

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Dataplane Records Search API
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+const { createDataplaneApiClient } = require('./index');
+const { normalizeRecordsSearchClientResponse } = require('./records-search-parse');
+
+/**
+ * Search records across datasources (governed read path).
+ * POST /api/v1/records/search
+ * @requiresPermission {Dataplane} record:search
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {import('./types/records-search.types').RecordsSearchRequest} body
+ * @returns {Promise<{ success: boolean, data: Array, meta: Object, links?: Object, status?: number }>}
+ */
+async function searchRecords(dataplaneUrl, authConfig, body) {
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig);
+  const raw = await client.post('/api/v1/records/search', { body });
+  return normalizeRecordsSearchClientResponse(raw);
+}
+
+module.exports = {
+  searchRecords,
+  normalizeRecordsSearchClientResponse
+};

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

@@ -0,0 +1,67 @@
+/**
+ * @fileoverview Agent metadata validation API types (dataplane 404.5)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+/**
+ * @typedef {'info' | 'warning' | 'error'} AgentValidationFindingSeverity
+ */
+
+/**
+ * @typedef {Object} AgentValidationFinding
+ * @property {AgentValidationFindingSeverity} severity
+ * @property {string} code
+ * @property {string} message
+ * @property {string} [field]
+ * @property {string} [recommendation]
+ */
+
+/**
+ * @typedef {'pending' | 'passed' | 'warning' | 'failed'} AgentValidationStatus
+ */
+
+/**
+ * @typedef {'trusted' | 'usableWithWarnings' | 'notTrusted' | 'pending'} AgentTrustDecision
+ */
+
+/**
+ * @typedef {Object} AgentMetadataValidationResult
+ * @property {AgentValidationStatus} status
+ * @property {AgentTrustDecision} trustDecision
+ * @property {number} confidence
+ * @property {string} summary
+ * @property {AgentValidationFinding[]} findings
+ * @property {string} validatedAt - ISO 8601
+ * @property {string} inputHash
+ * @property {string} contractVersion
+ */
+
+/**
+ * @typedef {Object} AgentMetadataValidationRunRequest
+ * @property {boolean} [forceRevalidate]
+ * @property {Object<string, Object>} [peerDatasourceConfigs]
+ */
+
+/**
+ * @typedef {Object} AgentMetadataValidationRunResponse
+ * @property {string} id
+ * @property {string} externalDataSourceId
+ * @property {string} datasourceKey
+ * @property {AgentMetadataValidationResult} result
+ * @property {boolean} [reused]
+ */
+
+/**
+ * @typedef {Object} AgentMetadataValidationHistoryItem
+ * @property {string} id
+ * @property {string} inputHash
+ * @property {string} contractVersion
+ * @property {AgentTrustDecision} trustDecision
+ * @property {AgentValidationStatus} validationStatus
+ * @property {number} confidence
+ * @property {string} validatedAt
+ * @property {boolean} isLatest
+ */
+
+module.exports = {};

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