@bpmsoftwaresolutions/ai-engine-client 1.1.83 → 1.1.86

package/src/domains/transfer-bundles.js

@@ -0,0 +1,372 @@
+import {
+  cleanText,
+  isPlainObject,
+  normalizeRecipientMode,
+  normalizeTransferKind,
+  normalizeTransferLifecycleStatus,
+  normalizeTransferMode,
+  normalizeTransferReceiptType,
+} from '../utils/communication.js';
+
+export function createTransferBundlesDomain(client) {
+  return {
+    transferWorkPacket: (request) => transferWorkPacket(client, request),
+    getTransferBundle: (bundleId) => getCommunicationBundle(client, bundleId),
+    listTransferBundles: (request) => listCommunicationBundles(client, request),
+    createTransferReceipt: (request) => recordCommunicationTransferReceipt(client, request),
+    listTransferReceipts: (request) => listTransferReceipts(client, request),
+    createCommunicationBundle: (request) => createCommunicationBundle(client, request),
+    getCommunicationBundle: (bundleId) => getCommunicationBundle(client, bundleId),
+    listCommunicationBundles: (request) => listCommunicationBundles(client, request),
+    addCommunicationBundleItem: (request) => addCommunicationBundleItem(client, request),
+    uploadCommunicationBundle: (request) => uploadCommunicationBundle(client, request),
+    attachCommunicationBundleToMessage: (request) => attachCommunicationBundleToMessage(client, request),
+    recordCommunicationBundleReceipt: (request) => recordCommunicationBundleReceipt(client, request),
+    recordCommunicationBundleCleanupEvent: (request) => recordCommunicationBundleCleanupEvent(client, request),
+    claimCommunicationBundle: (request) => claimCommunicationBundle(client, request),
+    recordCommunicationTransferReceipt: (request) => recordCommunicationTransferReceipt(client, request),
+  };
+}
+
+export async function transferWorkPacket(client, request = {}) {
+  const normalizedTarget = isPlainObject(request.target) ? request.target : {};
+  const normalizedWorkflowRunId = cleanText(request.workflow_run_id) || cleanText(request.workflowRunId);
+  const normalizedTransferKind = normalizeTransferKind(request.transfer_kind ?? request.transferKind ?? 'upstream_remediation');
+  const normalizedPreferredModes = Array.isArray(request.preferred_modes)
+    ? request.preferred_modes
+    : (Array.isArray(request.preferredModes) ? request.preferredModes : (Array.isArray(request.preferred) ? request.preferred : ['bundle', 'artifact_refs', 'inline_payload']));
+  const normalizedTargetMode = cleanText(normalizedTarget.recipient_mode) || cleanText(normalizedTarget.recipientMode) || cleanText(request.recipient_mode) || cleanText(request.recipientMode) || 'role';
+  return client._request('/api/agent-communications/work-transfers', {
+    method: 'POST',
+    body: {
+      workflow_run_id: normalizedWorkflowRunId,
+      transfer_kind: normalizedTransferKind,
+      objective: cleanText(request.objective),
+      requested_outcome: cleanText(request.requested_outcome) || cleanText(request.requestedOutcome),
+      target: {
+        intent: cleanText(normalizedTarget.intent) || normalizedTransferKind,
+        recipient_mode: normalizeRecipientMode(normalizedTargetMode),
+        preferred_role_key: cleanText(normalizedTarget.preferred_role_key) || cleanText(normalizedTarget.preferredRoleKey) || cleanText(request.recipient_role_key) || cleanText(request.recipientRoleKey),
+        preferred_agent_session_id: cleanText(normalizedTarget.preferred_agent_session_id) || cleanText(normalizedTarget.preferredAgentSessionId) || cleanText(request.recipient_agent_session_id) || cleanText(request.recipientAgentSessionId),
+      },
+      artifacts: Array.isArray(request.artifacts) ? request.artifacts : [],
+      issues: Array.isArray(request.issues) ? request.issues : [],
+      expected_evidence: Array.isArray(request.expectedEvidence) ? request.expectedEvidence : [],
+      preferred_modes: normalizedPreferredModes.map((mode) => normalizeTransferMode(mode)),
+      capabilities: isPlainObject(request.capabilities) ? request.capabilities : {},
+      estimated_payload_kb: Number(request.estimated_payload_kb ?? request.estimatedPayloadKb ?? 0) || undefined,
+      requires_receipts: Boolean(request.requires_receipts ?? request.requiresReceipts),
+      supports_hash_validation: Boolean(request.supports_hash_validation ?? request.supportsHashValidation),
+      sender_agent_session_id: cleanText(request.sender_agent_session_id) || cleanText(request.senderAgentSessionId) || client.agentSessionId,
+      sender_actor_session_id: cleanText(request.sender_actor_session_id) || cleanText(request.senderActorSessionId),
+      message_kind: cleanText(request.message_kind) || cleanText(request.messageKind),
+      subject: cleanText(request.subject),
+      body_markdown: cleanText(request.body_markdown) || cleanText(request.bodyMarkdown),
+      parent_thread_id: cleanText(request.parent_thread_id) || cleanText(request.parentThreadId),
+      cleanup_policy: cleanText(request.cleanup_policy) || cleanText(request.cleanupPolicy),
+    },
+  });
+}
+
+export async function listTransferReceipts(client, { workTransferPacketId, work_transfer_packet_id, workflowRunId, workflow_run_id } = {}) {
+  const normalizedPacketId = cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId);
+  if (!normalizedPacketId) throw new Error('work_transfer_packet_id is required.');
+  return client._request(`/api/agent-communications/transfers/${encodeURIComponent(normalizedPacketId)}/receipts`, {
+    method: 'GET',
+    query: {
+      workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+    },
+  });
+}
+
+export async function createTransferReceipt(client, request = {}) {
+  return recordCommunicationTransferReceipt(client, request);
+}
+
+export async function createCommunicationBundle(client, {
+  workflowRunId,
+  workflow_run_id,
+  communicationThreadId,
+  communication_thread_id,
+  threadId,
+  sourceAgentSessionId,
+  source_agent_session_id,
+  sourceActorSessionId,
+  source_actor_session_id,
+  recipientAgentSessionId,
+  recipient_agent_session_id,
+  recipientRoleKey,
+  recipient_role_key,
+  bundleKind,
+  bundle_kind,
+  cleanupPolicy,
+  cleanup_policy,
+  manifest = {},
+  manifestSha256,
+  manifest_sha256,
+  blobUri,
+  blob_uri,
+  blobSha256,
+  blob_sha256,
+  blobContainerName,
+  blob_container_name,
+  blobObjectKey,
+  blob_object_key,
+  metadata = {},
+} = {}) {
+  return client._request('/api/agent-communications/bundles', {
+    method: 'POST',
+    body: {
+      workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId),
+      communication_thread_id: cleanText(communication_thread_id) || cleanText(communicationThreadId) || cleanText(threadId),
+      source_agent_session_id: cleanText(source_agent_session_id) || cleanText(sourceAgentSessionId),
+      source_actor_session_id: cleanText(source_actor_session_id) || cleanText(sourceActorSessionId),
+      recipient_agent_session_id: cleanText(recipient_agent_session_id) || cleanText(recipientAgentSessionId),
+      recipient_role_key: cleanText(recipient_role_key) || cleanText(recipientRoleKey),
+      bundle_kind: cleanText(bundle_kind) || cleanText(bundleKind) || 'transfer',
+      cleanup_policy: cleanText(cleanup_policy) || cleanText(cleanupPolicy) || 'cleanup_after_receipt',
+      manifest: isPlainObject(manifest) ? manifest : {},
+      manifest_sha256: cleanText(manifest_sha256) || cleanText(manifestSha256),
+      blob_uri: cleanText(blob_uri) || cleanText(blobUri),
+      blob_sha256: cleanText(blob_sha256) || cleanText(blobSha256),
+      blob_container_name: cleanText(blob_container_name) || cleanText(blobContainerName),
+      blob_object_key: cleanText(blob_object_key) || cleanText(blobObjectKey),
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}
+
+export async function getCommunicationBundle(client, bundleId) {
+  return client._request(`/api/agent-communications/bundles/${encodeURIComponent(bundleId)}`);
+}
+
+export async function listCommunicationBundles(client, { workflowRunId, workflow_run_id } = {}) {
+  return client._request('/api/agent-communications/bundles', {
+    query: { workflow_run_id: cleanText(workflow_run_id) || cleanText(workflowRunId) },
+  });
+}
+
+export async function addCommunicationBundleItem(client, {
+  communicationBundleId,
+  communication_bundle_id,
+  itemOrder,
+  item_order,
+  itemKind,
+  item_kind,
+  itemRef,
+  item_ref,
+  itemName,
+  item_name,
+  itemSha256,
+  item_sha256,
+  required,
+  metadata = {},
+} = {}) {
+  const normalizedBundleId = cleanText(communication_bundle_id) || cleanText(communicationBundleId);
+  if (!normalizedBundleId) throw new Error('communication_bundle_id is required.');
+  return client._request(`/api/agent-communications/bundles/${encodeURIComponent(normalizedBundleId)}/items`, {
+    method: 'POST',
+    body: {
+      item_order: Number(item_order ?? itemOrder ?? 0),
+      item_kind: cleanText(item_kind) || cleanText(itemKind) || 'artifact',
+      item_ref: cleanText(item_ref) || cleanText(itemRef),
+      item_name: cleanText(item_name) || cleanText(itemName),
+      item_sha256: cleanText(item_sha256) || cleanText(itemSha256),
+      required: required !== undefined ? Boolean(required) : true,
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}
+
+export async function uploadCommunicationBundle(client, {
+  communicationBundleId,
+  communication_bundle_id,
+  blobUri,
+  blob_uri,
+  blobSha256,
+  blob_sha256,
+  blobContainerName,
+  blob_container_name,
+  blobObjectKey,
+  blob_object_key,
+  manifest = {},
+  manifestSha256,
+  manifest_sha256,
+  uploadedAt,
+  uploaded_at,
+} = {}) {
+  const normalizedBundleId = cleanText(communication_bundle_id) || cleanText(communicationBundleId);
+  if (!normalizedBundleId) throw new Error('communication_bundle_id is required.');
+  return client._request(`/api/agent-communications/bundles/${encodeURIComponent(normalizedBundleId)}/upload`, {
+    method: 'POST',
+    body: {
+      blob_uri: cleanText(blob_uri) || cleanText(blobUri),
+      blob_sha256: cleanText(blob_sha256) || cleanText(blobSha256),
+      blob_container_name: cleanText(blob_container_name) || cleanText(blobContainerName),
+      blob_object_key: cleanText(blob_object_key) || cleanText(blobObjectKey),
+      manifest: isPlainObject(manifest) ? manifest : {},
+      manifest_sha256: cleanText(manifest_sha256) || cleanText(manifestSha256),
+      uploaded_at: cleanText(uploaded_at) || cleanText(uploadedAt),
+    },
+  });
+}
+
+export async function attachCommunicationBundleToMessage(client, {
+  communicationBundleId,
+  communication_bundle_id,
+  agentMessageId,
+  agent_message_id,
+  messageId,
+  messageStatus,
+  message_status,
+} = {}) {
+  const normalizedBundleId = cleanText(communication_bundle_id) || cleanText(communicationBundleId);
+  if (!normalizedBundleId) throw new Error('communication_bundle_id is required.');
+  return client._request(`/api/agent-communications/bundles/${encodeURIComponent(normalizedBundleId)}/attach-to-message`, {
+    method: 'POST',
+    body: {
+      agent_message_id: cleanText(agent_message_id) || cleanText(agentMessageId) || cleanText(messageId),
+      message_status: cleanText(message_status) || cleanText(messageStatus),
+    },
+  });
+}
+
+export async function recordCommunicationBundleReceipt(client, {
+  communicationBundleId,
+  communication_bundle_id,
+  recipientAgentSessionId,
+  recipient_agent_session_id,
+  recipientActorSessionId,
+  recipient_actor_session_id,
+  receiptStatus,
+  receipt_status,
+  manifestSha256,
+  manifest_sha256,
+  blobSha256,
+  blob_sha256,
+  fetchedItemCount,
+  fetched_item_count,
+  explicitlyAcceptedItemCount,
+  explicitly_accepted_item_count,
+  allRequiredItemsFetched,
+  all_required_items_fetched,
+  checksumsVerified,
+  checksums_verified,
+  receipt = {},
+  metadata = {},
+} = {}) {
+  const normalizedBundleId = cleanText(communication_bundle_id) || cleanText(communicationBundleId);
+  if (!normalizedBundleId) throw new Error('communication_bundle_id is required.');
+  return client._request(`/api/agent-communications/bundles/${encodeURIComponent(normalizedBundleId)}/receipts`, {
+    method: 'POST',
+    body: {
+      recipient_agent_session_id: cleanText(recipient_agent_session_id) || cleanText(recipientAgentSessionId),
+      recipient_actor_session_id: cleanText(recipient_actor_session_id) || cleanText(recipientActorSessionId),
+      receipt_status: cleanText(receipt_status) || cleanText(receiptStatus) || 'received',
+      manifest_sha256: cleanText(manifest_sha256) || cleanText(manifestSha256),
+      blob_sha256: cleanText(blob_sha256) || cleanText(blobSha256),
+      fetched_item_count: Number(fetched_item_count ?? fetchedItemCount ?? 0),
+      explicitly_accepted_item_count: Number(explicitly_accepted_item_count ?? explicitlyAcceptedItemCount ?? 0),
+      all_required_items_fetched: Boolean(all_required_items_fetched ?? allRequiredItemsFetched ?? false),
+      checksums_verified: Boolean(checksums_verified ?? checksumsVerified ?? false),
+      receipt: isPlainObject(receipt) ? receipt : {},
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}
+
+export async function recordCommunicationBundleCleanupEvent(client, {
+  communicationBundleId,
+  communication_bundle_id,
+  cleanupStatus,
+  cleanup_status,
+  cleanupReason,
+  cleanup_reason,
+  blobUri,
+  blob_uri,
+  deletedAt,
+  deleted_at,
+  errorMessage,
+  error_message,
+  metadata = {},
+} = {}) {
+  const normalizedBundleId = cleanText(communication_bundle_id) || cleanText(communicationBundleId);
+  if (!normalizedBundleId) throw new Error('communication_bundle_id is required.');
+  return client._request(`/api/agent-communications/bundles/${encodeURIComponent(normalizedBundleId)}/cleanup-events`, {
+    method: 'POST',
+    body: {
+      cleanup_status: cleanText(cleanup_status) || cleanText(cleanupStatus) || 'cleanup_failed',
+      cleanup_reason: cleanText(cleanup_reason) || cleanText(cleanupReason),
+      blob_uri: cleanText(blob_uri) || cleanText(blobUri),
+      deleted_at: cleanText(deleted_at) || cleanText(deletedAt),
+      error_message: cleanText(error_message) || cleanText(errorMessage),
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}
+
+export async function claimCommunicationBundle(client, {
+  communicationBundleId,
+  communication_bundle_id,
+  claimedAt,
+  claimed_at,
+} = {}) {
+  const normalizedBundleId = cleanText(communication_bundle_id) || cleanText(communicationBundleId);
+  if (!normalizedBundleId) throw new Error('communication_bundle_id is required.');
+  return client._request(`/api/agent-communications/bundles/${encodeURIComponent(normalizedBundleId)}/claim`, {
+    method: 'POST',
+    body: {
+      claimed_at: cleanText(claimed_at) || cleanText(claimedAt),
+    },
+  });
+}
+
+export async function recordCommunicationTransferReceipt(client, {
+  workTransferPacketId,
+  work_transfer_packet_id,
+  receiptType,
+  receipt_type,
+  receiptStatus,
+  receipt_status,
+  actorSessionId,
+  actor_session_id,
+  agentSessionId,
+  agent_session_id,
+  claimId,
+  claim_id,
+  evidenceRef,
+  evidence_ref,
+  evidenceSha256,
+  evidence_sha256,
+  evidence = {},
+  manifestSha256,
+  manifest_sha256,
+  closureReason,
+  closure_reason,
+  failureReason,
+  failure_reason,
+  lifecycleStatus,
+  lifecycle_status,
+  metadata = {},
+} = {}) {
+  const normalizedPacketId = cleanText(work_transfer_packet_id) || cleanText(workTransferPacketId);
+  if (!normalizedPacketId) throw new Error('work_transfer_packet_id is required.');
+  return client._request(`/api/agent-communications/transfers/${encodeURIComponent(normalizedPacketId)}/receipts`, {
+    method: 'POST',
+    body: {
+      receipt_type: normalizeTransferReceiptType(cleanText(receipt_type) || cleanText(receiptType) || 'delivery_receipt'),
+      receipt_status: cleanText(receipt_status) || cleanText(receiptStatus) || 'recorded',
+      actor_session_id: cleanText(actor_session_id) || cleanText(actorSessionId),
+      agent_session_id: cleanText(agent_session_id) || cleanText(agentSessionId) || client.agentSessionId,
+      claim_id: cleanText(claim_id) || cleanText(claimId),
+      evidence_ref: cleanText(evidence_ref) || cleanText(evidenceRef),
+      evidence_sha256: cleanText(evidence_sha256) || cleanText(evidenceSha256),
+      evidence: isPlainObject(evidence) ? evidence : {},
+      manifest_sha256: cleanText(manifest_sha256) || cleanText(manifestSha256),
+      closure_reason: cleanText(closure_reason) || cleanText(closureReason),
+      failure_reason: cleanText(failure_reason) || cleanText(failureReason),
+      lifecycle_status: cleanText(lifecycle_status) || cleanText(lifecycleStatus),
+      metadata: isPlainObject(metadata) ? metadata : {},
+    },
+  });
+}