@bpmsoftwaresolutions/ai-engine-client 1.1.36 → 1.1.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmsoftwaresolutions/ai-engine-client",
-  "version": "1.1.36",
+  "version": "1.1.38",
   "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.36';
+export const AI_ENGINE_CLIENT_VERSION = '1.1.38';
 export const GOVERNED_MUTATION_REQUIRED_CAPABILITIES = [
   'executeVerifiedMutation',
   'post_mutation_verification',
@@ -114,6 +114,11 @@ function cleanText(value) {
   return text || null;
 }
 
+function looksLikeUuid(value) {
+  const text = cleanText(value);
+  return Boolean(text && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(text));
+}
+
 function countRoadmapProjectionLines(markdown) {
   const lines = [];
   let inSummary = false;
@@ -291,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 = {}) {
@@ -373,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 },
@@ -1674,6 +1783,14 @@ export class AIEngineClient {
       ...packetPayload,
       imported_by: normalizedImportedBy,
     });
+    const packetId = cleanText(importedPacket?.packet_id || importedPacket?.packetId || importedPacket?.implementation_packet_key || importedPacket?.implementationPacketKey || packetPayload.packetId || packetPayload.packet_id);
+    const implementationPacketId = cleanText(importedPacket?.implementation_packet_id || importedPacket?.implementationPacketId);
+    if (!implementationPacketId) {
+      throw new Error('Imported implementation packet response must include implementation_packet_id.');
+    }
+    if (!looksLikeUuid(implementationPacketId)) {
+      throw new Error('Imported implementation packet response returned a non-UUID implementation_packet_id.');
+    }
     const projectReference = this._resolveImplementationPacketProjectReference(packetPayload);
     if (!projectReference) {
       throw new Error('Could not resolve a project reference from the packet payload.');
@@ -1694,8 +1811,6 @@ export class AIEngineClient {
     }
     const resolvedWorkflowId = await this._resolveImplementationPacketWorkflowId(workflowReference);
     const workflowSlug = cleanText(projectSummary.workflow_slug);
-    const packetId = cleanText(importedPacket?.packet_id || importedPacket?.packetId || importedPacket?.implementation_packet_key || importedPacket?.implementationPacketKey || packetPayload.packetId || packetPayload.packet_id);
-    const implementationPacketId = cleanText(importedPacket?.implementation_packet_id || importedPacket?.implementationPacketId || packetId);
 
     const binding = await this.bindImplementationPacketToWorkflow(resolvedWorkflowId, {
       packet_id: packetId,