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

package/README.md

@@ -10,6 +10,17 @@ No repo clone required. Install the package, point it at the Azure service, and
 npm install @bpmsoftwaresolutions/ai-engine-client
 ```
 
+## Publishing
+
+This package is published automatically from GitHub Actions by `.github/workflows/publish-ai-engine-client.yml`.
+
+The workflow runs on pushes to `main` when files under `packages/ai-engine-client/**` change, and it can also be started manually with `workflow_dispatch`.
+
+Authentication supports either:
+
+- npm trusted publishing
+- a repository secret named `NPM_TOKEN`, `NPM_PUBLISH_TOKEN`, or `NODE_AUTH_TOKEN`
+
 ## Quick Start
 
 ```js
@@ -54,6 +65,98 @@ const persistedTurn = await client.persistAssistantTurn({
 });
 ```
 
+## Integration Notes
+
+### Auth Modes
+
+The package supports two authentication patterns:
+
+1. Bearer-token auth for operator and governed routes.
+2. Compatibility API-key auth for migration-oriented external routes and deployments that still allow shared-key access.
+
+Header behavior is:
+
+- If `accessToken` or `tokenProvider` is configured, the client sends `Authorization: Bearer <token>`.
+- If bearer auth is not configured, the client sends `X-API-Key` when `apiKey` is provided.
+- If bearer auth is not configured and `clientId` is provided, the client also sends `X-Client-Id`.
+- The client always sends `X-Actor-Id` for audit trails unless overridden.
+
+That means this package wraps both operator/governed routes and selected external `/api/v1/*` routes. Pick the auth mode that matches the route family exposed by your deployment.
+
+### Route Families
+
+- Operator and governed routes are methods such as `createProjectCharter`, `getProjectBundle`, `importImplementationPacket`, and the workflow/portfolio/governance APIs.
+- External routes are the methods prefixed with `getExternal*`, `listExternal*`, `downloadExternal*`, plus `startSessionGovernance`, `persistAssistantTurn`, `createExternalAudioRender`, and `getLatestMemoryProjection`.
+
+If your deployment enforces bearer auth on operator routes, API-key-only construction will not work for those methods.
+
+### Text and Binary Downloads
+
+Some methods do not return plain JSON:
+
+- 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:
+
+```js
+import fs from 'node:fs';
+
+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
@@ -101,6 +204,105 @@ const client = new AIEngineClient({
 
 When `accessToken` or `tokenProvider` is present, the client prefers bearer auth. API key headers are only sent when bearer auth is not configured.
 
+Some deployments accept a shared `X-API-Key` without `X-Client-Id`, while others require both `X-Client-Id` and `X-API-Key` for API-key auth. If your environment uses client-scoped API keys, provide both values.
+
+### Project Chartering Contract
+
+`createProjectCharter()` sends snake_case fields to `POST /api/projects/charter`. The method accepts:
+
+- `projectName`, `objective`
+- `businessContext`, `successCriteria`, `priority`
+- `constraints`, `inScope`, `outOfScope`, `assumptions`
+- `linkedWorkflows`, `linkedWorkflowSlug`
+- `testingStrategy`, `initialContext`
+- `requestedBy`
+- `ensureTaskSurface`, `assignedTo`, `createAcceptanceSubtasks`
+
+The response always includes the charter identifiers:
+
+- `project_id`
+- `workflow_id`
+- `workflow_run_id`
+- `implementation_packet_id`
+- `implementation_packet_key`
+- `status`
+
+If `ensureTaskSurface` is left as `true`, the server also attempts to attach `task_surface` for the active roadmap item. That field is only available when the server can resolve an active implementation item from the project roadmap. If roadmap state is incomplete in the deployment, charter creation can still succeed while `task_surface` is unavailable.
+
+Example:
+
+```js
+const charter = await client.createProjectCharter({
+  projectName: 'Loga Cognitive Interface Cockpit Delivery',
+  objective: 'Deliver the operator cockpit and playback experience.',
+  businessContext: 'Ground the first playback surface in convert-document-to-audio.',
+  linkedWorkflowSlug: 'convert-document-to-audio',
+  ensureTaskSurface: true,
+  createAcceptanceSubtasks: true,
+});
+
+console.log(charter.project_id);
+console.log(charter.implementation_packet_key);
+console.log(charter.task_surface?.active_item?.implementation_item_id ?? null);
+```
+
+### Implementation Packet Import Contract
+
+`importImplementationPacket(body)` expects the engine's `implementation_plan_packet` schema, not an arbitrary roadmap-shaped JSON document.
+
+Minimum required top-level fields:
+
+- `packetType`
+- `packetVersion`
+- `packetId`
+- `title`
+- `phases`
+- `governance.requiredGates`
+
+Minimum required fields for each item:
+
+- `itemKey`
+- `type`
+- `description`
+- `acceptanceChecks`
+
+Allowed packet statuses include `draft`, `approved`, `blocked`, `completed`, and other governed packet lifecycle states. Custom statuses such as `draft-local-artifact` are not valid for import.
+
+Minimal example:
+
+```js
+await client.importImplementationPacket({
+  packetType: 'implementation_plan_packet',
+  packetVersion: '1.0',
+  packetId: 'impl-loga-cockpit-v1',
+  title: 'Loga Cognitive Interface Cockpit Delivery',
+  status: 'draft',
+  governance: {
+    requiredGates: ['intent', 'structure', 'promotion'],
+  },
+  phases: [
+    {
+      phaseKey: 'phase_1_foundation',
+      title: 'Foundation',
+      items: [
+        {
+          itemKey: 'define-cockpit-surface',
+          type: 'ui_slice',
+          description: 'Define the first cockpit delivery slice.',
+          acceptanceChecks: [
+            { text: 'The initial slice is explicitly bounded.' },
+          ],
+        },
+      ],
+    },
+  ],
+});
+```
+
+The package does not auto-convert nested human planning structures like `tasks` and `subtasks` into durable implementation-item tasks. To create persisted task records after import, use `ensureProjectRoadmapTaskSurface()` or `createImplementationTask()`.
+
+A copyable example payload is packaged at `examples/implementation-plan-packet.minimal.json`.
+
 ### External Audio Render Example
 
 ```js
@@ -166,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 |
 |---|---|
@@ -449,4 +662,4 @@ Low-level compatibility methods:
 
 The package talks to the AI Engine web service. All routes listed above are registered unconditionally in the Flask app and served by the deployed Azure Container App.
 
-Operator and governed routes expect bearer-token authorization. The external v1 API (`/api/v1/*`) still supports its migration auth modes separately and is intentionally not wrapped by this client.
+Operator and governed routes generally expect bearer-token authorization. The package also wraps selected external `/api/v1/*` routes that support migration-oriented auth modes such as bearer or API-key compatibility, depending on deployment configuration.

package/examples/implementation-plan-packet.minimal.json

@@ -0,0 +1,76 @@
+{
+  "packetType": "implementation_plan_packet",
+  "packetVersion": "1.0",
+  "packetId": "impl-example-governed-slice-v1",
+  "title": "Example Governed Slice Implementation Packet",
+  "status": "draft",
+  "createdBy": {
+    "kind": "operator",
+    "name": "sdk-example"
+  },
+  "sourceModel": {
+    "producer": "ai-engine-client-readme",
+    "purpose": "minimal_import_example"
+  },
+  "system": {
+    "slug": "example-governed-slice",
+    "domain": "project-chartering"
+  },
+  "scope": {
+    "productArea": "example-governed-slice",
+    "workflowIntent": "Demonstrate the minimum durable implementation packet contract.",
+    "targetSurface": "governed-project-execution",
+    "inScope": [
+      "first delivery slice"
+    ],
+    "outOfScope": [
+      "full product rollout"
+    ]
+  },
+  "northStar": {
+    "summary": "Define a small but valid governed implementation packet."
+  },
+  "governance": {
+    "requiredGates": [
+      "intent",
+      "structure",
+      "promotion"
+    ],
+    "reviewRequired": true,
+    "evidenceRequiredForCompletion": true
+  },
+  "completionPolicy": {
+    "requiresEvidence": true,
+    "requiresReview": true
+  },
+  "phases": [
+    {
+      "phaseKey": "phase_1_foundation",
+      "title": "Foundation",
+      "items": [
+        {
+          "itemKey": "define-first-slice",
+          "type": "delivery_slice",
+          "priority": "high",
+          "title": "Define first governed slice",
+          "description": "Define the first durable delivery slice and bind its acceptance criteria.",
+          "status": "not_started",
+          "dependsOn": [],
+          "artifactsExpected": [
+            "delivery-slice-definition.md"
+          ],
+          "acceptanceChecks": [
+            {
+              "text": "The slice is explicitly bounded.",
+              "status": "not_run"
+            },
+            {
+              "text": "The slice can be attached to durable task surfaces.",
+              "status": "not_run"
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmsoftwaresolutions/ai-engine-client",
-  "version": "1.0.0-beta.10",
+  "version": "1.0.0-beta.12",
   "description": "Thin npm client for the AI Engine operator and retrieval APIs",
   "type": "module",
   "main": "./src/index.js",
@@ -12,7 +12,8 @@
   },
   "files": [
     "src",
-    "README.md"
+    "README.md",
+    "examples"
   ],
   "engines": {
     "node": ">=18"

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();