@aifabrix/builder 2.50.0 → 2.51.1

package/lib/api/evidence-authoring-helpers.js

@@ -0,0 +1,267 @@
+/**
+ * @fileoverview Helper utilities for BTA-facing Evidence authoring APIs
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { unwrapApiData } = require('../utils/external-system-readiness-core');
+
+const VALIDATION_STATUS_PASSED = 'passed';
+const VALIDATION_STATUS_FAILED = 'failed';
+const EVIDENCE_WRITABLE_FIELDS = Object.freeze([
+  'key',
+  'resourceType',
+  'roleKey',
+  'kindKey',
+  'kindVersion',
+  'aspect',
+  'title',
+  'description',
+  'when',
+  'expectedBehavior',
+  'order',
+  'status',
+  'suggestionExplanation',
+  'contributionOverrides',
+  'approval'
+]);
+const EVIDENCE_REQUIRED_FIELDS = Object.freeze(['title', 'when', 'expectedBehavior']);
+
+/**
+ * @param {*} value
+ * @returns {string}
+ */
+function trimString(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+/**
+ * @param {*} res
+ * @returns {*}
+ */
+function unwrapBody(res) {
+  return unwrapApiData(res) ?? res;
+}
+
+/**
+ * @param {*} res
+ * @param {string} action
+ * @returns {*}
+ */
+function assertApiSuccess(res, action) {
+  if (res && res.success === false) {
+    const message = res.formattedError || res.error || `${action} failed`;
+    const err = new Error(message);
+    err.status = res.status;
+    err.errorData = res.errorData;
+    throw err;
+  }
+  return res;
+}
+
+/**
+ * @param {*} value
+ * @returns {Object[]}
+ */
+function extractCollectionRows(value) {
+  if (Array.isArray(value)) {
+    return value;
+  }
+  const candidates = [
+    value?.data?.items,
+    value?.data?.rows,
+    value?.data?.data,
+    value?.items,
+    value?.rows,
+    value?.data
+  ];
+  for (const candidate of candidates) {
+    if (Array.isArray(candidate)) {
+      return candidate;
+    }
+  }
+  return [];
+}
+
+/**
+ * @param {Object} row
+ * @returns {string}
+ */
+function buildEvidenceRowSignature(row) {
+  return `${trimString(row?.title)}|${trimString(row?.when)}|${trimString(row?.expectedBehavior)}`;
+}
+
+/**
+ * @param {Object} row
+ * @returns {string}
+ */
+function normalizeEvidenceRef(row) {
+  const candidates = [row?.id, row?.key];
+  for (const candidate of candidates) {
+    const normalized = trimString(candidate);
+    if (normalized) {
+      return normalized;
+    }
+  }
+  return '';
+}
+
+/**
+ * @param {Object[]} rows
+ * @returns {Map<string, string[]>}
+ */
+function buildEvidenceReferenceBuckets(rows) {
+  const buckets = new Map();
+  for (const row of rows) {
+    const ref = normalizeEvidenceRef(row);
+    if (!ref) {
+      continue;
+    }
+    const signature = buildEvidenceRowSignature(row);
+    if (!signature || signature === '||') {
+      continue;
+    }
+    const refs = buckets.get(signature) || [];
+    refs.push(ref);
+    buckets.set(signature, refs);
+  }
+  return buckets;
+}
+
+/**
+ * @param {Map<string, string[]>} buckets
+ * @param {string} signature
+ * @returns {string}
+ */
+function consumeReferenceForSignature(buckets, signature) {
+  const refs = buckets.get(signature);
+  if (!Array.isArray(refs) || refs.length === 0) {
+    return '';
+  }
+  const ref = refs.shift();
+  if (refs.length === 0) {
+    buckets.delete(signature);
+  }
+  return ref;
+}
+
+/**
+ * @param {*} payload
+ * @returns {Object[]}
+ */
+function normalizeCandidateRows(payload) {
+  if (Array.isArray(payload)) {
+    return payload;
+  }
+  if (payload && Array.isArray(payload.rows)) {
+    return payload.rows;
+  }
+  if (payload && payload.row && typeof payload.row === 'object') {
+    return [payload.row];
+  }
+  return [];
+}
+
+/**
+ * @param {Object[]} rows
+ * @param {string} roleKey
+ * @returns {{ acceptedRows: Object[], acceptedIndexes: number[], rejected: Object[] }}
+ */
+function partitionUploadRows(rows, roleKey) {
+  const acceptedRows = [];
+  const acceptedIndexes = [];
+  const rejected = [];
+  for (let index = 0; index < rows.length; index += 1) {
+    const row = rows[index];
+    if (!row || typeof row !== 'object' || Array.isArray(row)) {
+      rejected.push({ index, error: 'Row must be an object.' });
+      continue;
+    }
+    const rowRoleKey = trimString(row.roleKey);
+    if (rowRoleKey && rowRoleKey !== roleKey) {
+      rejected.push({ index, error: `Row roleKey "${rowRoleKey}" does not match "${roleKey}".` });
+      continue;
+    }
+    acceptedRows.push({ ...row, roleKey });
+    acceptedIndexes.push(index);
+  }
+  return { acceptedRows, acceptedIndexes, rejected };
+}
+
+/**
+ * @param {Object} detail
+ * @returns {string[]}
+ */
+function extractAssistantCapabilities(detail) {
+  const payload = unwrapBody(detail);
+  const candidates = [
+    payload?.capabilities,
+    payload?.assistantCapabilities,
+    payload?.data?.capabilities,
+    payload?.data?.assistantCapabilities
+  ];
+  for (const candidate of candidates) {
+    if (Array.isArray(candidate)) {
+      return candidate
+        .map((row) => (typeof row === 'string' ? row : (row?.key || row?.name || null)))
+        .filter(Boolean);
+    }
+  }
+  return [];
+}
+
+/**
+ * @param {Object} params
+ * @returns {Object}
+ */
+function buildDownloadQuery(params) {
+  const query = {};
+  for (const [key, value] of Object.entries(params || {})) {
+    if (value === undefined || value === null || value === '') {
+      continue;
+    }
+    query[key] = value;
+  }
+  return query;
+}
+
+/**
+ * @param {Object} params
+ * @returns {import('./types/evidence.types').EvidenceUploadResponse}
+ */
+function buildUploadResult(params) {
+  const rejected = params.rejected || [];
+  const certified = params.certified || [];
+  return {
+    roleKey: params.roleKey,
+    inserted: Number(params.loadResult?.inserted || 0),
+    updated: Number(params.loadResult?.updated || 0),
+    accepted: params.accepted || [],
+    rejected,
+    warnings: params.warnings || [],
+    certified,
+    readyToActivate: certified.length > 0 && rejected.length === 0
+  };
+}
+
+module.exports = {
+  VALIDATION_STATUS_PASSED,
+  VALIDATION_STATUS_FAILED,
+  EVIDENCE_WRITABLE_FIELDS,
+  EVIDENCE_REQUIRED_FIELDS,
+  trimString,
+  unwrapBody,
+  assertApiSuccess,
+  extractCollectionRows,
+  buildEvidenceRowSignature,
+  normalizeEvidenceRef,
+  buildEvidenceReferenceBuckets,
+  consumeReferenceForSignature,
+  normalizeCandidateRows,
+  partitionUploadRows,
+  extractAssistantCapabilities,
+  buildDownloadQuery,
+  buildUploadResult
+};

package/lib/api/evidence-authoring.api.js

@@ -0,0 +1,337 @@
+/**
+ * @fileoverview BTA-facing Evidence authoring APIs (metadata, download, upload, activate)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { createDataplaneApiClient } = require('./index');
+const { listEvidenceKinds } = require('./evidence-kinds.api');
+const { listResourceTypes } = require('./resource-types.api');
+const { getAssistantDetails } = require('./assistants.api');
+const {
+  listEvidence,
+  loadEvidenceBulk,
+  validateEvidenceCandidate,
+  certifyEvidenceCandidate,
+  activateEvidenceCandidate
+} = require('./evidence.api');
+const {
+  VALIDATION_STATUS_PASSED,
+  VALIDATION_STATUS_FAILED,
+  EVIDENCE_WRITABLE_FIELDS,
+  EVIDENCE_REQUIRED_FIELDS,
+  trimString,
+  unwrapBody,
+  assertApiSuccess,
+  extractCollectionRows,
+  buildEvidenceRowSignature,
+  normalizeEvidenceRef,
+  buildEvidenceReferenceBuckets,
+  consumeReferenceForSignature,
+  normalizeCandidateRows,
+  partitionUploadRows,
+  extractAssistantCapabilities,
+  buildDownloadQuery,
+  buildUploadResult
+} = require('./evidence-authoring-helpers');
+
+const BASE = '/api/v1/evidence';
+
+/**
+ * @param {Object} ctx
+ * @returns {Promise<Map<string, string[]>>}
+ */
+async function listRoleEvidenceReferenceBuckets(ctx) {
+  const roleRows = await listEvidence(ctx.dataplaneUrl, ctx.authConfig, { roleKey: ctx.roleKey }, ctx.options);
+  return buildEvidenceReferenceBuckets(roleRows);
+}
+
+/**
+ * @param {Object} ctx
+ * @param {Object[]} loadedRows
+ * @param {Object[]} uploadRows
+ * @returns {Promise<string[]>}
+ */
+async function resolveUploadEvidenceRefs(ctx, loadedRows, uploadRows) {
+  const refs = [];
+  const loadedBuckets = buildEvidenceReferenceBuckets(loadedRows);
+  let roleBuckets = null;
+
+  for (let i = 0; i < uploadRows.length; i += 1) {
+    const refFromLoad = normalizeEvidenceRef(loadedRows[i]);
+    if (refFromLoad) {
+      refs.push(refFromLoad);
+      continue;
+    }
+    const signature = buildEvidenceRowSignature(uploadRows[i]);
+    let ref = signature ? consumeReferenceForSignature(loadedBuckets, signature) : '';
+    if (!ref && signature) {
+      if (!roleBuckets) {
+        roleBuckets = await listRoleEvidenceReferenceBuckets(ctx);
+      }
+      ref = consumeReferenceForSignature(roleBuckets, signature);
+    }
+    refs.push(ref || '');
+  }
+  return refs;
+}
+
+/**
+ * @param {Object} params
+ * @returns {Promise<{ accepted: Object[], rejected: Object[], warnings: Object[], certified: Object[] }>}
+ */
+async function processUploadedRowsLifecycle(params) {
+  const { dataplaneUrl, authConfig, options, refs, acceptedRows, acceptedIndexes, rejected, certifyPayload } = params;
+  const accepted = [];
+  const certified = [];
+  const warnings = [];
+
+  for (let i = 0; i < acceptedRows.length; i += 1) {
+    const outcome = await processUploadedEvidenceRow({
+      dataplaneUrl,
+      authConfig,
+      options,
+      evidenceRef: refs[i],
+      rowIndex: acceptedIndexes[i],
+      certifyPayload
+    });
+    applyLifecycleOutcome({ outcome, rejected, warnings, accepted, certified });
+  }
+  return { accepted, rejected, warnings, certified };
+}
+
+/**
+ * @param {Object} params
+ * @param {Object} params.outcome
+ * @param {Object[]} params.rejected
+ * @param {Object[]} params.warnings
+ * @param {Object[]} params.accepted
+ * @param {Object[]} params.certified
+ */
+function applyLifecycleOutcome(params) {
+  const { outcome, rejected, warnings, accepted, certified } = params;
+  if (outcome.rejection) {
+    rejected.push(outcome.rejection);
+  }
+  if (outcome.warning) {
+    warnings.push(outcome.warning);
+  }
+  if (outcome.accepted) {
+    accepted.push(outcome.accepted);
+  }
+  if (outcome.certified) {
+    certified.push(outcome.certified);
+  }
+}
+
+/**
+ * @param {Object} params
+ * @returns {Promise<{ rejection?: Object, warning?: Object, accepted?: Object, certified?: Object }>}
+ */
+async function processUploadedEvidenceRow(params) {
+  const { dataplaneUrl, authConfig, options, evidenceRef, rowIndex, certifyPayload } = params;
+  if (!evidenceRef) {
+    return {
+      rejection: { index: rowIndex, error: 'Could not resolve uploaded row id/key.' }
+    };
+  }
+  const validation = await validateEvidenceCandidate(dataplaneUrl, authConfig, evidenceRef, options);
+  const validationStatus = trimString(validation?.status).toLowerCase();
+  if (validationStatus === VALIDATION_STATUS_FAILED || validationStatus !== VALIDATION_STATUS_PASSED) {
+    const issues = Array.isArray(validation?.issues) ? validation.issues : [];
+    return {
+      rejection: {
+        index: rowIndex,
+        evidenceRef,
+        error: `Validation status "${validation?.status || 'unknown'}".`,
+        issues
+      },
+      warning: issues.length > 0 ? { index: rowIndex, evidenceRef, issues } : null
+    };
+  }
+  const certification = await certifyEvidenceCandidate(
+    dataplaneUrl,
+    authConfig,
+    evidenceRef,
+    certifyPayload,
+    options
+  );
+  return {
+    accepted: { index: rowIndex, evidenceRef, status: VALIDATION_STATUS_PASSED },
+    certified: {
+      index: rowIndex,
+      evidenceRef,
+      status: trimString(certification?.status) || 'candidate',
+      data: certification
+    }
+  };
+}
+
+/**
+ * BTA-facing metadata API for Evidence authoring.
+ *
+ * @requiresPermission {Dataplane} worker:read + evidence:read
+ * @requiresPermission {Controller} evidence-kinds:read + resource-types:read
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {string} roleKey
+ * @param {Object} [options]
+ * @param {string} [options.controllerUrl]
+ * @returns {Promise<import('./types/evidence.types').EvidenceAuthoringMetadata>}
+ */
+async function getEvidenceMetadata(dataplaneUrl, authConfig, roleKey, options = {}) {
+  const normalizedRoleKey = trimString(roleKey);
+  if (!normalizedRoleKey) {
+    throw new Error('roleKey is required for evidence.metadata');
+  }
+  if (!trimString(options.controllerUrl)) {
+    throw new Error('controllerUrl is required for evidence.metadata');
+  }
+
+  const [assistantDetails, evidenceKindsRes, resourceTypesRes, evidenceRows] = await Promise.all([
+    getAssistantDetails(dataplaneUrl, normalizedRoleKey, authConfig),
+    listEvidenceKinds(options.controllerUrl, authConfig, { page: 1, pageSize: 500 }),
+    listResourceTypes(options.controllerUrl, authConfig, { page: 1, pageSize: 500 }),
+    listEvidence(dataplaneUrl, authConfig, { roleKey: normalizedRoleKey }, options)
+  ]);
+
+  const evidenceKinds = extractCollectionRows(evidenceKindsRes).map((row) => ({
+    key: row.key || null,
+    version: row.version || row.kindVersion || row.metadata?.version || null,
+    displayName: row.displayName || null,
+    purpose: row.purpose || null
+  }));
+  const resourceTypes = extractCollectionRows(resourceTypesRes).map((row) => ({
+    key: row.key || row.resourceType || null,
+    displayName: row.displayName || null,
+    category: row.category || null
+  }));
+  const aspects = Array.from(new Set(evidenceRows.map((row) => trimString(row?.aspect)).filter(Boolean))).sort();
+
+  return {
+    roleKey: normalizedRoleKey,
+    evidenceKinds,
+    aspects,
+    resourceTypes,
+    assistantCapabilities: extractAssistantCapabilities(assistantDetails),
+    writableFields: [...EVIDENCE_WRITABLE_FIELDS],
+    requiredFields: [...EVIDENCE_REQUIRED_FIELDS],
+    constraints: {
+      certification: { validationStatus: VALIDATION_STATUS_PASSED, candidateStatus: 'candidate' },
+      activation: { requiresCertified: true, requiresAuthority: true }
+    }
+  };
+}
+
+/**
+ * BTA-facing download/search projection over the existing Evidence list/search route.
+ *
+ * @requiresPermission {Dataplane} evidence:read
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {import('./types/evidence.types').EvidenceDownloadParams} params
+ * @param {Object} [options]
+ * @returns {Promise<import('./types/evidence.types').EvidenceDownloadResponse>}
+ */
+async function downloadEvidence(dataplaneUrl, authConfig, params = {}, options = {}) {
+  const roleKey = trimString(params.roleKey);
+  if (!roleKey) {
+    throw new Error('roleKey is required for evidence.download');
+  }
+  const client = createDataplaneApiClient(dataplaneUrl, authConfig, {
+    controllerUrl: options.controllerUrl || null
+  });
+  const query = buildDownloadQuery({ ...params, roleKey });
+  const res = assertApiSuccess(await client.get(BASE, { params: query }), 'Download evidence');
+  const rows = extractCollectionRows(unwrapBody(res));
+  return { roleKey, count: rows.length, data: rows };
+}
+
+/**
+ * BTA-facing upload API: load + validate + certify valid rows, never activate.
+ *
+ * @requiresPermission {Dataplane} evidence:create + evidence:update
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {import('./types/evidence.types').EvidenceUploadRequest|Object[]} payload
+ * @param {Object} [options]
+ * @returns {Promise<import('./types/evidence.types').EvidenceUploadResponse>}
+ */
+async function uploadEvidenceCandidates(dataplaneUrl, authConfig, payload = {}, options = {}) {
+  const roleKey = trimString(payload?.roleKey || options?.roleKey);
+  if (!roleKey) {
+    throw new Error('roleKey is required for evidence.upload');
+  }
+  const rows = normalizeCandidateRows(payload);
+  const { acceptedRows, acceptedIndexes, rejected } = partitionUploadRows(rows, roleKey);
+  if (acceptedRows.length === 0) {
+    return buildUploadResult({ roleKey, accepted: [], rejected, warnings: [], certified: [] });
+  }
+
+  const loadResult = await loadEvidenceBulk(dataplaneUrl, authConfig, acceptedRows, options);
+  const refs = await resolveUploadEvidenceRefs(
+    { dataplaneUrl, authConfig, roleKey, options },
+    Array.isArray(loadResult.data) ? loadResult.data : [],
+    acceptedRows
+  );
+  const certifyPayload = trimString(payload?.comment) ? { comment: trimString(payload.comment) } : {};
+  const lifecycle = await processUploadedRowsLifecycle({
+    dataplaneUrl,
+    authConfig,
+    options,
+    refs,
+    acceptedRows,
+    acceptedIndexes,
+    rejected,
+    certifyPayload
+  });
+  return buildUploadResult({ roleKey, loadResult, ...lifecycle });
+}
+
+/**
+ * BTA-facing activation API for one or many human-approved certified evidence IDs.
+ *
+ * @requiresPermission {Dataplane} evidence:update
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @param {import('./types/evidence.types').EvidenceActivateRequest} payload
+ * @param {Object} [options]
+ * @returns {Promise<import('./types/evidence.types').EvidenceActivateResponse>}
+ */
+async function activateEvidenceCandidates(dataplaneUrl, authConfig, payload = {}, options = {}) {
+  const evidenceIds = Array.from(
+    new Set(
+      (Array.isArray(payload?.evidenceIds) ? payload.evidenceIds : [])
+        .map((value) => trimString(value))
+        .filter(Boolean)
+    )
+  );
+  if (evidenceIds.length === 0) {
+    throw new Error('evidenceIds[] is required for evidence.activate');
+  }
+
+  const activated = [];
+  const failed = [];
+  for (const evidenceId of evidenceIds) {
+    try {
+      const result = await activateEvidenceCandidate(dataplaneUrl, authConfig, evidenceId, options);
+      activated.push({ evidenceId, result });
+    } catch (error) {
+      failed.push({ evidenceId, error: error?.message || String(error), status: error?.status || null });
+    }
+  }
+  return { requested: evidenceIds.length, activated, failed, success: failed.length === 0 };
+}
+
+module.exports = {
+  getEvidenceMetadata,
+  downloadEvidence,
+  uploadEvidenceCandidates,
+  activateEvidenceCandidates
+};