@bpmsoftwaresolutions/ai-engine-client 1.0.0-beta.11 → 1.0.0-beta.12

package/README.md

@@ -94,7 +94,8 @@ If your deployment enforces bearer auth on operator routes, API-key-only constru
 
 Some methods do not return plain JSON:
 
-- Markdown download helpers return `{ text, contentType, fileName }`.
+- Markdown download helpers return `{ text, contentType, fileName, headers }`.
+- LOGA projection helpers return markdown plus governed projection metadata: `{ text, contentType, headers, logaContract, interactionContract, projectionType, projectionVersion, sourceTruth, sourceVersion, correlationId, refreshPolicy, generatedAt, provenance }`.
 - Binary download helpers return `{ arrayBuffer, contentType, fileName }`.
 
 Examples:
@@ -106,10 +107,56 @@ const markdown = await client.downloadProjectCharterReportMarkdown(projectId);
 console.log(markdown.fileName, markdown.contentType);
 console.log(markdown.text);
 
+const logaRoadmap = await client.getLogaProjectRoadmapProjection(projectId);
+console.log(logaRoadmap.projectionType, logaRoadmap.projectionVersion);
+console.log(logaRoadmap.provenance.sourceTruth, logaRoadmap.correlationId);
+console.log(logaRoadmap.text);
+
 const audio = await client.downloadExternalAudioRender(audioRenderRunId);
 await fs.promises.writeFile('render.mp3', Buffer.from(audio.arrayBuffer));
 ```
 
+### LOGA Projection Contract
+
+LOGA should use the `getLoga*Projection()` methods for runtime documents. These endpoints are governed AI Engine transformations: durable SQL state is normalized into typed projection models, transformed into versioned structured markdown, and served with provenance, refresh, and action metadata for LOGA to render.
+
+The client exposes the transport metadata from response headers so LOGA can validate the contract before rendering:
+
+- `logaContract`: currently `ai-engine-ui/v1`
+- `interactionContract`: currently `loga-choreography/v1`
+- `projectionType`: for example `operator.project_roadmap`
+- `projectionWorkflow`: currently `loga-document-projection`
+- `projectionVersion`
+- `sourceTruth`: normally `sql`
+- `sourceVersion`
+- `correlationId`
+- `refreshPolicy`
+- `generatedAt`
+- `provenance`: grouped copy of the source/projection/version fields
+
+Example:
+
+```js
+import {
+  AIEngineClient,
+  LOGA_CONTRACT,
+  LOGA_INTERACTION_CONTRACT,
+} from '@bpmsoftwaresolutions/ai-engine-client';
+
+const client = AIEngineClient.fromEnv();
+const projection = await client.getLogaProjectRoadmapProjection(projectId);
+
+if (projection.logaContract !== LOGA_CONTRACT) {
+  throw new Error(`Unsupported LOGA contract: ${projection.logaContract}`);
+}
+
+console.log(projection.interactionContract === LOGA_INTERACTION_CONTRACT);
+renderLogaMarkdown(projection.text, {
+  projectionType: projection.projectionType,
+  provenance: projection.provenance,
+});
+```
+
 ### fromEnv
 
 ```js
@@ -321,6 +368,17 @@ Low-level compatibility methods:
 | `listAzureSqlBacpacBackups({ storageAccount, container, ... })` | List BACPAC exports through the legacy infra-shaped operator API. |
 | `listAzureSqlBacpacBackupOperations({ databaseName, resourceGroup, serverName, ... })` | List Azure SQL operations through the legacy infra-shaped operator API. |
 
+### LOGA Projections
+| Method | Endpoint | Description |
+|---|---|---|
+| `getLogaOperatorHomeProjection()` | `GET /api/operator/projections/home` | Governed operator home runtime markdown document. |
+| `getLogaProjectCatalogProjection()` | `GET /api/operator/projections/project-catalog` | Governed project catalog runtime markdown document. |
+| `getLogaProjectRoadmapProjection(projectId)` | `GET /api/operator/projections/projects/:projectId/roadmap.md` | Governed project roadmap runtime markdown document. |
+| `getLogaWorkflowRunProjection(workflowRunId)` | `GET /api/operator/projections/workflow-runs/:workflowRunId` | Governed workflow run runtime markdown document. |
+| `getLogaEvidencePacketProjection(packetKey)` | `GET /api/operator/projections/evidence-packets/:packetKey` | Governed evidence packet runtime markdown document. |
+
+These methods return markdown as `text` and expose projection headers as top-level fields plus `provenance`. LOGA should render the markdown emitted by AI Engine and use these metadata fields for contract validation, refresh behavior, evidence display, and action choreography.
+
 ### Retrieval Wrapper
 | Method | Description |
 |---|---|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmsoftwaresolutions/ai-engine-client",
-  "version": "1.0.0-beta.11",
+  "version": "1.0.0-beta.12",
   "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,9 @@
 const DEFAULT_TIMEOUT_MS = 30000;
 
+export const LOGA_CONTRACT = 'ai-engine-ui/v1';
+export const LOGA_INTERACTION_CONTRACT = 'loga-choreography/v1';
+export const LOGA_PROJECTION_WORKFLOW = 'loga-document-projection';
+
 function trimTrailingSlash(value) {
   return String(value || '').replace(/\/+$/, '');
 }
@@ -28,6 +32,44 @@ function parseContentDispositionFilename(headerValue) {
   return plainMatch ? plainMatch[1].trim() : null;
 }
 
+function readResponseHeader(headers, name) {
+  if (!headers || typeof headers.get !== 'function') return null;
+  return headers.get(name) || headers.get(name.toLowerCase()) || null;
+}
+
+function extractLogaProjectionMetadata(headers) {
+  const projectionWorkflow = readResponseHeader(headers, 'x-projection-workflow');
+  const projectionVersion = readResponseHeader(headers, 'x-projection-version');
+  const sourceVersion = readResponseHeader(headers, 'x-source-version');
+  const correlationId = readResponseHeader(headers, 'x-correlation-id');
+  const logaContract = readResponseHeader(headers, 'x-loga-contract');
+  const projectionType = readResponseHeader(headers, 'x-projection-type');
+  const sourceTruth = readResponseHeader(headers, 'x-source-truth');
+  const refreshPolicy = readResponseHeader(headers, 'x-refresh-policy');
+  const generatedAt = readResponseHeader(headers, 'x-generated-at');
+
+  return {
+    logaContract,
+    interactionContract: LOGA_INTERACTION_CONTRACT,
+    projectionType,
+    projectionWorkflow,
+    projectionVersion,
+    sourceTruth,
+    sourceVersion,
+    correlationId,
+    refreshPolicy,
+    generatedAt,
+    provenance: {
+      sourceTruth,
+      sourceVersion,
+      projectionVersion,
+      projectionWorkflow,
+      correlationId,
+      generatedAt,
+    },
+  };
+}
+
 function isFormDataBody(value) {
   return typeof FormData !== 'undefined' && value instanceof FormData;
 }
@@ -709,6 +751,28 @@ export class AIEngineClient {
     return this._request(`/api/operator/projects/${projectId}/bundle`);
   }
 
+  // LOGA projections are governed runtime documents, not static reports.
+
+  async getLogaOperatorHomeProjection() {
+    return this._requestLogaProjection('/api/operator/projections/home');
+  }
+
+  async getLogaProjectCatalogProjection() {
+    return this._requestLogaProjection('/api/operator/projections/project-catalog');
+  }
+
+  async getLogaProjectRoadmapProjection(projectId) {
+    return this._requestLogaProjection(`/api/operator/projections/projects/${projectId}/roadmap.md`);
+  }
+
+  async getLogaWorkflowRunProjection(workflowRunId) {
+    return this._requestLogaProjection(`/api/operator/projections/workflow-runs/${workflowRunId}`);
+  }
+
+  async getLogaEvidencePacketProjection(packetKey) {
+    return this._requestLogaProjection(`/api/operator/projections/evidence-packets/${packetKey}`);
+  }
+
   // ─── Roadmaps ──────────────────────────────────────────────────────────────
 
   async listProjectRoadmaps({ includeInactive } = {}) {
@@ -1393,12 +1457,21 @@ export class AIEngineClient {
         text: await response.text(),
         contentType,
         fileName: parseContentDispositionFilename(contentDisposition),
+        headers: Object.fromEntries(response.headers.entries()),
       };
     } finally {
       clearTimeout(timeoutHandle);
     }
   }
 
+  async _requestLogaProjection(path, options = {}) {
+    const result = await this._requestText(path, options);
+    return {
+      ...result,
+      ...extractLogaProjectionMetadata(new Headers(result.headers || {})),
+    };
+  }
+
   async _requestBinary(path, { method = 'GET', query, headers, body } = {}) {
     const url = appendQuery(`${this.baseUrl}${path}`, query);
     const controller = new AbortController();