@bpmsoftwaresolutions/ai-engine-client 1.1.55 → 1.1.57

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmsoftwaresolutions/ai-engine-client",
-  "version": "1.1.55",
+  "version": "1.1.57",
   "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.55';
+export const AI_ENGINE_CLIENT_VERSION = '1.1.57';
 export const GOVERNED_MUTATION_REQUIRED_CAPABILITIES = [
   'executeVerifiedMutation',
   'post_mutation_verification',
@@ -409,7 +409,7 @@ export class AIEngineClient {
       openThread: (request) => this.openCommunicationThread(request),
       getThread: (threadId) => this.getCommunicationThread(threadId),
       listInbox: (request) => this.listCommunicationInbox(request),
-      sendMessage: (request) => this.sendCommunicationMessage(request),
+      sendMessage: (request) => this._sendAgentCommsMessage(request),
       getCommunicationCapabilities: (request) => this.getCommunicationCapabilities(request),
       getCollaborationCapabilities: (request) => this.getCollaborationCapabilities(request),
       getDeploymentCapabilities: (request) => this.getDeploymentCapabilities(request),
@@ -440,9 +440,20 @@ export class AIEngineClient {
       acceptHandoff: (request) => this.acceptCommunicationHandoff(request),
       whoIsOnline: (request) => this.whoIsOnline(request),
       findOnlineParticipant: (request) => this.findOnlineParticipant(request),
+      listCommunicationChannels: (request) => this.listCommunicationChannels(request),
+      listOpenCommunicationChannels: (request) => this.listOpenCommunicationChannels(request),
+      getCommunicationChannelStatus: (request) => this.getCommunicationChannelStatus(request),
+      getCommunicationChannelParticipants: (request) => this.getCommunicationChannelParticipants(request),
+      getPresenceBoard: (request) => this.getPresenceBoard(request),
+      getChannelPresence: (request) => this.getChannelPresence(request),
+      markParticipantOnline: (request) => this.markParticipantOnline(request),
+      markParticipantOffline: (request) => this.markParticipantOffline(request),
       sendToParticipant: (request) => this.sendToParticipant(request),
       sendToRole: (request) => this.sendToRole(request),
       getMyInbox: (request) => this.getMyInbox(request),
+      verifyMessageSent: (request) => this.verifyMessageSent(request),
+      verifyMessageReceived: (request) => this.verifyMessageReceived(request),
+      getMessageDeliveryReceipt: (request) => this.getMessageDeliveryReceipt(request),
       connectToTransferChannel: (request) => this.connectToTransferChannel(request),
       respondToMessageWatch: (request) => this.respondToMessageWatch(request),
     };
@@ -456,9 +467,21 @@ export class AIEngineClient {
       requestClosure: (request) => this.requestCollaborationClosure(request),
       whoIsOnline: (request) => this.whoIsOnline(request),
       findOnlineParticipant: (request) => this.findOnlineParticipant(request),
+      listCommunicationChannels: (request) => this.listCommunicationChannels(request),
+      listOpenCommunicationChannels: (request) => this.listOpenCommunicationChannels(request),
+      getCommunicationChannelStatus: (request) => this.getCommunicationChannelStatus(request),
+      getCommunicationChannelParticipants: (request) => this.getCommunicationChannelParticipants(request),
+      getPresenceBoard: (request) => this.getPresenceBoard(request),
+      getChannelPresence: (request) => this.getChannelPresence(request),
+      markParticipantOnline: (request) => this.markParticipantOnline(request),
+      markParticipantOffline: (request) => this.markParticipantOffline(request),
       sendToParticipant: (request) => this.sendToParticipant(request),
       sendToRole: (request) => this.sendToRole(request),
       getMyInbox: (request) => this.getMyInbox(request),
+      sendMessage: (request) => this._sendAgentCommsMessage(request),
+      verifyMessageSent: (request) => this.verifyMessageSent(request),
+      verifyMessageReceived: (request) => this.verifyMessageReceived(request),
+      getMessageDeliveryReceipt: (request) => this.getMessageDeliveryReceipt(request),
     };
   }
 
@@ -649,6 +672,197 @@ export class AIEngineClient {
     return this._request('/api/agent-communications/deployment-capabilities');
   }
 
+  async listCommunicationChannels({
+    workflowRunId,
+    workflow_run_id,
+    workTransferPacketId,
+    work_transfer_packet_id,
+    status,
+    channelStatus,
+    channel_status,
+  } = {}) {
+    return this._request('/api/agent-communications/transfer-channels', {
+      query: {
+        workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+        work_transfer_packet_id: cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId),
+        status: cleanText(status) || cleanText(channel_status) || cleanText(channelStatus),
+      },
+    });
+  }
+
+  async listOpenCommunicationChannels(request = {}) {
+    return this.listCommunicationChannels({ ...request, status: 'open' });
+  }
+
+  async getCommunicationChannelStatus({
+    transferChannelId,
+    transfer_channel_id,
+    channelId,
+    channel_id,
+  } = {}) {
+    const normalizedTransferChannelId = cleanText(transfer_channel_id) || cleanText(transferChannelId) || cleanText(channel_id) || cleanText(channelId);
+    if (!normalizedTransferChannelId) throw new Error('transferChannelId is required.');
+    return this._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/status`);
+  }
+
+  async getCommunicationChannelParticipants({
+    transferChannelId,
+    transfer_channel_id,
+    channelId,
+    channel_id,
+  } = {}) {
+    const normalizedTransferChannelId = cleanText(transfer_channel_id) || cleanText(transferChannelId) || cleanText(channel_id) || cleanText(channelId);
+    if (!normalizedTransferChannelId) throw new Error('transferChannelId is required.');
+    return this._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/participants`);
+  }
+
+  async getPresenceBoard({
+    workflowRunId,
+    workflow_run_id,
+    transferChannelId,
+    transfer_channel_id,
+    participantRole,
+    participant_role,
+    role,
+    capability,
+    includeStale,
+    include_stale,
+  } = {}) {
+    const normalizedTransferChannelId = cleanText(transfer_channel_id) || cleanText(transferChannelId);
+    const path = normalizedTransferChannelId
+      ? `/api/operator/projections/agent-communications/presence/${encodeURIComponent(normalizedTransferChannelId)}`
+      : '/api/operator/projections/agent-communications/presence';
+    return this._requestLogaProjection(path, {
+      query: {
+        workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+        transfer_channel_id: normalizedTransferChannelId,
+        participant_role: cleanText(participant_role) || cleanText(participantRole) || cleanText(role),
+        capability: cleanText(capability),
+        include_stale: include_stale ?? includeStale,
+      },
+    });
+  }
+
+  async getChannelPresence({
+    transferChannelId,
+    transfer_channel_id,
+    channelId,
+    channel_id,
+    workflowRunId,
+    workflow_run_id,
+    participantRole,
+    participant_role,
+    role,
+    capability,
+    includeStale,
+    include_stale,
+  } = {}) {
+    const normalizedTransferChannelId = cleanText(transfer_channel_id) || cleanText(transferChannelId) || cleanText(channel_id) || cleanText(channelId);
+    if (!normalizedTransferChannelId) {
+      throw new Error('transferChannelId is required.');
+    }
+    return this._requestLogaProjection(`/api/operator/projections/agent-communications/presence/${encodeURIComponent(normalizedTransferChannelId)}`, {
+      query: {
+        workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+        participant_role: cleanText(participant_role) || cleanText(participantRole) || cleanText(role),
+        capability: cleanText(capability),
+        include_stale: include_stale ?? includeStale,
+      },
+    });
+  }
+
+  async markParticipantOnline({
+    transferChannelId,
+    transfer_channel_id,
+    channelId,
+    channel_id,
+    workTransferPacketId,
+    work_transfer_packet_id,
+    packetId,
+    packet_id,
+    workflowRunId,
+    workflow_run_id,
+    participantRole,
+    participant_role,
+    currentPhase,
+    current_phase,
+    currentTaskSummary,
+    current_task_summary,
+    agentSessionId,
+    agent_session_id,
+    actorSessionId,
+    actor_session_id,
+    observedAt,
+    observed_at,
+    metadata = {},
+  } = {}) {
+    const normalizedTransferChannelId = cleanText(transfer_channel_id) || cleanText(transferChannelId) || cleanText(channel_id) || cleanText(channelId);
+    if (!normalizedTransferChannelId) throw new Error('transferChannelId is required.');
+    return this._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/presence/online`, {
+      method: 'POST',
+      body: {
+        transfer_channel_id: normalizedTransferChannelId,
+        work_transfer_packet_id: cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId) || cleanText(packet_id) || cleanText(packetId),
+        workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+        participant_role: cleanText(participant_role) || cleanText(participantRole),
+        current_phase: cleanText(current_phase) || cleanText(currentPhase),
+        current_task_summary: cleanText(current_task_summary) || cleanText(currentTaskSummary),
+        agent_session_id: cleanText(agent_session_id) || cleanText(agentSessionId),
+        actor_session_id: cleanText(actor_session_id) || cleanText(actorSessionId),
+        observed_at: cleanText(observed_at) || cleanText(observedAt),
+        metadata: isPlainObject(metadata) ? metadata : {},
+        is_active: true,
+        activity_state: 'active',
+      },
+    });
+  }
+
+  async markParticipantOffline({
+    transferChannelId,
+    transfer_channel_id,
+    channelId,
+    channel_id,
+    workTransferPacketId,
+    work_transfer_packet_id,
+    packetId,
+    packet_id,
+    workflowRunId,
+    workflow_run_id,
+    participantRole,
+    participant_role,
+    currentPhase,
+    current_phase,
+    currentTaskSummary,
+    current_task_summary,
+    agentSessionId,
+    agent_session_id,
+    actorSessionId,
+    actor_session_id,
+    observedAt,
+    observed_at,
+    metadata = {},
+  } = {}) {
+    const normalizedTransferChannelId = cleanText(transfer_channel_id) || cleanText(transferChannelId) || cleanText(channel_id) || cleanText(channelId);
+    if (!normalizedTransferChannelId) throw new Error('transferChannelId is required.');
+    return this._request(`/api/agent-communications/transfer-channels/${encodeURIComponent(normalizedTransferChannelId)}/presence/offline`, {
+      method: 'POST',
+      body: {
+        transfer_channel_id: normalizedTransferChannelId,
+        work_transfer_packet_id: cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId) || cleanText(packet_id) || cleanText(packetId),
+        workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+        participant_role: cleanText(participant_role) || cleanText(participantRole),
+        current_phase: cleanText(current_phase) || cleanText(currentPhase),
+        current_task_summary: cleanText(current_task_summary) || cleanText(currentTaskSummary),
+        agent_session_id: cleanText(agent_session_id) || cleanText(agentSessionId),
+        actor_session_id: cleanText(actor_session_id) || cleanText(actorSessionId),
+        observed_at: cleanText(observed_at) || cleanText(observedAt),
+        metadata: isPlainObject(metadata) ? metadata : {},
+        is_active: false,
+        activity_state: 'offline',
+      },
+    });
+  }
+
   async reviewCollaborationProposal({
     transferChannelId,
     transfer_channel_id,
@@ -1462,6 +1676,89 @@ export class AIEngineClient {
     });
   }
 
+  async verifyMessageSent({ messageId, message_id } = {}) {
+    const normalizedMessageId = cleanText(message_id) || cleanText(messageId);
+    if (!normalizedMessageId) throw new Error('message_id is required.');
+    return this._request(`/api/agent-communications/messages/${encodeURIComponent(normalizedMessageId)}/verify-sent`, {
+      method: 'POST',
+      body: { message_id: normalizedMessageId },
+    });
+  }
+
+  async verifyMessageReceived({
+    messageId,
+    message_id,
+    recipientAgentSessionId,
+    recipient_agent_session_id,
+    recipientRole,
+    recipient_role,
+    role,
+    participantId,
+    participant_id,
+  } = {}) {
+    const normalizedMessageId = cleanText(message_id) || cleanText(messageId);
+    if (!normalizedMessageId) throw new Error('message_id is required.');
+    return this._request(`/api/agent-communications/messages/${encodeURIComponent(normalizedMessageId)}/verify-received`, {
+      method: 'POST',
+      body: {
+        message_id: normalizedMessageId,
+        recipient_agent_session_id: cleanText(recipient_agent_session_id) || cleanText(recipientAgentSessionId),
+        recipient_role: cleanText(recipient_role) || cleanText(recipientRole) || cleanText(role),
+        participant_id: cleanText(participant_id) || cleanText(participantId),
+      },
+    });
+  }
+
+  async getMessageDeliveryReceipt({ messageId, message_id } = {}) {
+    const normalizedMessageId = cleanText(message_id) || cleanText(messageId);
+    if (!normalizedMessageId) throw new Error('message_id is required.');
+    return this._request(`/api/agent-communications/messages/${encodeURIComponent(normalizedMessageId)}/delivery-receipt`, {
+      method: 'GET',
+    });
+  }
+
+  async _sendAgentCommsMessage(request = {}) {
+    const hasThreadContext = Boolean(
+      cleanText(request.communication_thread_id)
+      || cleanText(request.communicationThreadId)
+      || cleanText(request.thread_id)
+      || cleanText(request.threadId)
+      || cleanText(request.recipient_role_key)
+      || cleanText(request.recipientRoleKey)
+    );
+    const hasTransferChannelContext = Boolean(
+      cleanText(request.transfer_channel_id)
+      || cleanText(request.transferChannelId)
+      || cleanText(request.channel_id)
+      || cleanText(request.channelId)
+      || cleanText(request.sender_role)
+      || cleanText(request.senderRole)
+      || cleanText(request.recipient_role)
+      || cleanText(request.recipientRole)
+      || cleanText(request.role)
+      || cleanText(request.participant_role)
+      || cleanText(request.participantRole)
+      || cleanText(request.participant_id)
+      || cleanText(request.participantId)
+      || cleanText(request.recipient_participant_id)
+      || cleanText(request.recipientParticipantId)
+    );
+    if (hasTransferChannelContext && !hasThreadContext) {
+      if (
+        cleanText(request.participant_id)
+        || cleanText(request.participantId)
+        || cleanText(request.recipient_participant_id)
+        || cleanText(request.recipientParticipantId)
+        || cleanText(request.recipient_agent_session_id)
+        || cleanText(request.recipientAgentSessionId)
+      ) {
+        return this.sendToParticipant(request);
+      }
+      return this.sendToRole(request);
+    }
+    return this.sendCommunicationMessage(request);
+  }
+
   async sendCommunicationMessage({
     communicationThreadId,
     communication_thread_id,