@bpmsoftwaresolutions/ai-engine-client 1.1.37 → 1.1.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmsoftwaresolutions/ai-engine-client",
-  "version": "1.1.37",
+  "version": "1.1.39",
   "description": "Thin npm client for the AI Engine operator and retrieval APIs",
   "type": "module",
   "main": "./src/index.js",

package/src/index.js

@@ -1,5 +1,5 @@
 const DEFAULT_TIMEOUT_MS = 30000;
-export const AI_ENGINE_CLIENT_VERSION = '1.1.37';
+export const AI_ENGINE_CLIENT_VERSION = '1.1.39';
 export const GOVERNED_MUTATION_REQUIRED_CAPABILITIES = [
   'executeVerifiedMutation',
   'post_mutation_verification',
@@ -296,6 +296,15 @@ export class AIEngineClient {
       submitArtifact: (scriptId, payload) => this.submitScriptArtifact(scriptId, payload),
       getRunEvidence: (query) => this.getScriptRunEvidence(query),
     };
+    this.reports = {
+      run: (request) => this.runReportDefinition(request),
+    };
+    this.projections = {
+      render: (request) => this.renderProjection(request),
+    };
+    this.actions = {
+      submit: (request) => this.submitActionIntent(request),
+    };
   }
 
   static fromEnv(options = {}) {
@@ -378,6 +387,101 @@ export class AIEngineClient {
     return this._request('/api/v1/latest-memory-projection');
   }
 
+  // ─── Data Access Gateway ──────────────────────────────────────────────────
+
+  async query({
+    surface,
+    contractKey,
+    parameters = {},
+    fields = [],
+    fieldAllowlist = [],
+    actorScopes = [],
+    requiredScopes = [],
+    shape = 'json',
+    requestedBy,
+  } = {}) {
+    const normalizedSurface = cleanText(surface) || cleanText(contractKey);
+    if (!normalizedSurface) {
+      throw new Error('surface is required.');
+    }
+    const normalizedShape = cleanText(shape) || 'json';
+    if (!['json', 'table', 'cards', 'markdown'].includes(normalizedShape)) {
+      throw new Error('shape must be one of json, table, cards, or markdown.');
+    }
+    const normalizedFields = cleanList(fields);
+    const normalizedAllowlist = cleanList(fieldAllowlist);
+    const disallowedFields = normalizedFields.filter((field) => !normalizedAllowlist.includes(field));
+    if (normalizedAllowlist.length > 0 && disallowedFields.length > 0) {
+      throw new Error(`Requested fields are not allowed: ${disallowedFields.join(', ')}.`);
+    }
+    const normalizedActorScopes = cleanList(actorScopes);
+    const normalizedRequiredScopes = cleanList(requiredScopes);
+    const missingScopes = normalizedRequiredScopes.filter((scope) => !normalizedActorScopes.includes(scope));
+    if (missingScopes.length > 0) {
+      throw new Error(`Missing required scopes: ${missingScopes.join(', ')}.`);
+    }
+    return this._request('/api/gateway/query', {
+      method: 'POST',
+      body: {
+        surface: normalizedSurface,
+        parameters: isPlainObject(parameters) ? parameters : {},
+        fields: normalizedFields,
+        field_allowlist: normalizedAllowlist,
+        actor_scopes: normalizedActorScopes,
+        required_scopes: normalizedRequiredScopes,
+        shape: normalizedShape,
+        requested_by: cleanText(requestedBy),
+      },
+    });
+  }
+
+  async runReportDefinition({ reportKey, definition = {}, requestedBy } = {}) {
+    const normalizedReportKey = cleanText(reportKey);
+    if (!normalizedReportKey) {
+      throw new Error('reportKey is required.');
+    }
+    return this._request('/api/gateway/reports/run', {
+      method: 'POST',
+      body: {
+        report_key: normalizedReportKey,
+        definition: isPlainObject(definition) ? definition : {},
+        requested_by: cleanText(requestedBy),
+      },
+    });
+  }
+
+  async renderProjection({ projectionType, viewContract = {}, requestedBy } = {}) {
+    const normalizedProjectionType = cleanText(projectionType);
+    if (!normalizedProjectionType) {
+      throw new Error('projectionType is required.');
+    }
+    return this._request('/api/gateway/projections/render', {
+      method: 'POST',
+      body: {
+        projection_type: normalizedProjectionType,
+        view_contract: isPlainObject(viewContract) ? viewContract : {},
+        requested_by: cleanText(requestedBy),
+      },
+    });
+  }
+
+  async submitActionIntent({ action, target = {}, payload = {}, requiredScope, requestedBy } = {}) {
+    const normalizedAction = cleanText(action);
+    if (!normalizedAction) {
+      throw new Error('action is required.');
+    }
+    return this._request('/api/gateway/actions/submit', {
+      method: 'POST',
+      body: {
+        action: normalizedAction,
+        target: isPlainObject(target) ? target : {},
+        payload: isPlainObject(payload) ? payload : {},
+        required_scope: cleanText(requiredScope) || 'ai-engine.write',
+        requested_by: cleanText(requestedBy),
+      },
+    });
+  }
+
   async currentProjectStatus({ projectId } = {}) {
     return this._request('/api/operator/current-project-status', {
       query: { project_id: projectId },
@@ -1437,6 +1541,76 @@ export class AIEngineClient {
     return this._request(`/api/operator/projects/${projectId}`);
   }
 
+  async listProjectWorkflowRuns(projectId, { limit = 25 } = {}) {
+    return this._request(`/api/operator/projects/${projectId}/workflow-runs`, {
+      query: { limit },
+    });
+  }
+
+  async closeProject(projectId, {
+    workflowId,
+    workflowRunIds,
+    reason,
+    operatorIdentity,
+    runTerminalStatus = 'failed',
+  } = {}) {
+    const normalizedProjectId = cleanText(projectId);
+    if (!normalizedProjectId) {
+      throw new Error('projectId is required.');
+    }
+    const normalizedReason = cleanText(reason) || 'close active project';
+    const normalizedOperatorIdentity = cleanText(operatorIdentity) || this.actorId;
+    const resolvedRuns = Array.isArray(workflowRunIds) ? cleanList(workflowRunIds) : [];
+    let resolvedWorkflowId = cleanText(workflowId);
+
+    if (!resolvedWorkflowId || resolvedRuns.length === 0) {
+      const projectPayload = await this.getProject(normalizedProjectId);
+      const summary = isPlainObject(projectPayload?.summary) ? projectPayload.summary : {};
+      if (!resolvedWorkflowId) {
+        resolvedWorkflowId = cleanText(summary.workflow_id) || cleanText(summary.workflowId);
+      }
+      if (resolvedRuns.length === 0) {
+        const workflowRuns = await this.listProjectWorkflowRuns(normalizedProjectId, { limit: 100 });
+        const activeStatuses = new Set(['queued', 'running', 'blocked', 'open', 'active', 'ping-review']);
+        const activeRuns = Array.isArray(workflowRuns)
+          ? workflowRuns.filter((run) => activeStatuses.has(String(run?.status || '').trim().toLowerCase()))
+          : [];
+        for (const run of activeRuns) {
+          const runId = cleanText(run.workflow_run_id || run.workflowRunId);
+          if (runId && !resolvedRuns.includes(runId)) {
+            resolvedRuns.push(runId);
+          }
+          if (!resolvedWorkflowId) {
+            resolvedWorkflowId = cleanText(run.workflow_id || run.workflowId) || resolvedWorkflowId;
+          }
+        }
+      }
+    }
+
+    if (!resolvedWorkflowId) {
+      throw new Error('workflowId could not be resolved for project cleanup.');
+    }
+    if (resolvedRuns.length === 0) {
+      throw new Error('workflowRunIds could not be resolved for project cleanup.');
+    }
+
+    return this._request('/api/operator/cleanup', {
+      method: 'POST',
+      body: {
+        project_id: normalizedProjectId,
+        workflow_id: resolvedWorkflowId,
+        workflow_run_ids: resolvedRuns,
+        reason: normalizedReason,
+        operator_identity: normalizedOperatorIdentity,
+        run_terminal_status: cleanText(runTerminalStatus) || 'failed',
+      },
+    });
+  }
+
+  async closeActiveProject(projectId, options = {}) {
+    return this.closeProject(projectId, options);
+  }
+
   async getProjectCharterReport(projectId) {
     return this._request(`/api/operator/projects/${projectId}/charter/report`);
   }