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

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,51 @@ 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 }`.
+- 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 audio = await client.downloadExternalAudioRender(audioRenderRunId);
+await fs.promises.writeFile('render.mp3', Buffer.from(audio.arrayBuffer));
+```
+
 ### fromEnv
 
 ```js
@@ -101,6 +157,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
@@ -449,4 +604,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.11",
   "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"