@epam/ai-dial-chat-hooks 1.2.0-dev.12 → 1.2.0-dev.123

package/conversation.d.ts

@@ -15,7 +15,6 @@ import { Message } from '@epam/ai-dial-chat-shared';
 import { MessageCustomContent } from '@epam/ai-dial-chat-shared';
 import { MessageRating } from '@epam/ai-dial-chat-shared';
 import { MutableRefObject } from 'react';
-import { OverlayChatMessage } from '@epam/ai-dial-chat-overlay';
 import { PublishHistoryEntry } from '@epam/ai-dial-publish-panel';
 import { RateApi } from '@epam/ai-dial-chat-api-client';
 import { ReactNode } from 'react';
@@ -24,6 +23,7 @@ import { RequestSkill } from '@epam/ai-dial-chat-shared';
 import { ResponseFormat } from '@epam/ai-dial-chat-shared';
 import { SendCompletionDtoModeEnum } from '@epam/ai-dial-chat-api-client';
 import { SetStateAction } from 'react';
+import { Stage } from '@epam/ai-dial-chat-shared';
 import { StarterOption } from '@epam/ai-dial-chat-shared';
 import { StatusMessage } from '@epam/ai-dial-chat-shared';
 import { StreamChunk } from '@epam/ai-dial-chat-shared';
@@ -58,6 +58,25 @@ export declare interface AnnouncementListItemLink {
     href: string;
 }
 
+/**
+ * Applies a single SSE stream chunk to the message list.
+ *
+ *
+ * Attachments are accumulated: each chunk's attachments are appended to the
+ * existing array rather than replacing it.
+ *
+ * Annotations are merged by `index`: partial `body.title` and `body.quote`
+ * strings are concatenated across chunks, matching the same delta-merge
+ * semantics used for stages.
+ *
+ * `state` is overwritten (not merged) by each chunk that carries one,
+ * matching the DIAL stateful-app contract.
+ *
+ * @returns Updated message array, or `null` when the chunk carries no
+ *   actionable data (empty content, no form_schema, and no attachments).
+ */
+export declare const applyChunkToMessages: (messages: Message[], messageIndex: number, chunk: StreamChunk) => Message[] | null;
+
 /** State and controls returned by `useAsyncConfirmDialog`. */
 export declare interface AsyncConfirmDialogControls<T> {
     /**
@@ -573,6 +592,29 @@ declare interface LocalModeValues {
     temperature: number;
 }
 
+/**
+ * Returns the normalized stages of a raw stage array or a message-like
+ * payload (reading `custom_content.stages`, falling back to
+ * `customContent.stages`), or `undefined` when there are none.
+ */
+export declare const mapStages: (source: RawStage[] | RawStageSource | null | undefined) => Stage[] | undefined;
+
+/**
+ * Merges incoming stage deltas into an existing stage list, keyed by `index`.
+ *
+ * Partial `name` and `content` strings are concatenated across chunks;
+ * attachments are merged by their own `index` (concatenating partial `title`
+ * and `data`); every other field on the incoming delta overwrites the
+ * accumulated one. A brand-new stage whose first chunk carries `name: null`
+ * is normalized to `''`.
+ *
+ * Exported for hosts that keep a flattened `Stage[]` on the message instead
+ * of `Message.custom_content.stages` and therefore cannot reuse
+ * {@link applyChunkToMessages}. Prefer `useConversationStream` when the host
+ * can delegate the whole stream loop.
+ */
+export declare const mergeStages: (existing: Stage[], incoming: Stage[]) => Stage[];
+
 /** True when `message` is an assistant message carrying at least one stage. */
 export declare const messageHasStages: (message: Message) => boolean;
 
@@ -606,6 +648,63 @@ export declare interface QuickAppConversationStartersSettings {
     isChatMessageInputDisabled: boolean;
 }
 
+/**
+ * One stage as it arrives from the REST API or the SSE stream, before
+ * normalization. Structurally satisfied by the generated `StageDto` and by a
+ * raw stream delta, both of which omit `index`/`name`/`status` on the chunk
+ * that opens a stage.
+ */
+export declare interface RawStage {
+    /** Ordering key. Defaults to `0` when absent. */
+    index?: number | null;
+    /** Stage title. `null` on the chunk that opens the stage. */
+    name?: string | null;
+    /** Terminal state as a raw wire string; anything other than `'completed'`/`'failed'` means still running. */
+    status?: string | null;
+    /** Additional stage text. */
+    content?: string | null;
+    /** Short source/category label shown beside the stage name. */
+    tag?: string | null;
+    /** Files produced or referenced by this stage. */
+    attachments?: RawStageAttachment[] | null;
+}
+
+/**
+ * One stage attachment as it arrives from the REST API or the SSE stream,
+ * before normalization: every field is optional and may be `null`.
+ */
+export declare interface RawStageAttachment {
+    /** Zero-based position in the attachment list. */
+    index?: number | null;
+    /** MIME type of the attachment content. */
+    type?: string | null;
+    /** Display name shown in the UI. */
+    title?: string | null;
+    /** Inline base-64 encoded content. */
+    data?: string | null;
+    /** Remote URL pointing to the attachment content. */
+    url?: string | null;
+    /** MIME type of the referenced resource. */
+    reference_type?: string | null;
+    /** URL of an alternate reference resource. */
+    reference_url?: string | null;
+}
+
+/**
+ * Message-like payload carrying stages under either the wire's snake_case
+ * `custom_content` or a host's camelCased `customContent`.
+ */
+export declare interface RawStageSource {
+    /** Custom content as the DIAL wire format spells it. */
+    custom_content?: {
+        stages?: RawStage[] | null;
+    } | null;
+    /** Custom content as a camelCasing host spells it. */
+    customContent?: {
+        stages?: RawStage[] | null;
+    } | null;
+}
+
 /** State of one resource's recipient-count lookup. */
 declare interface RecipientsCountEntry {
     /** Where the lookup for this resource currently stands. */
@@ -662,8 +761,23 @@ export declare interface StreamCompletionOptions {
     signal: AbortSignal;
 }
 
-/** Maps chat messages to the DIAL Chat Overlay protocol's message shape. */
-export declare const toOverlayMessages: (messages: Message[]) => OverlayChatMessage[];
+/**
+ * Reported through `onError` when DIAL Core itself signals a failure with an
+ * in-band `{ error: { message } }` SSE chunk. Its `message` is upstream text
+ * intended for the user, unlike a transport failure (failed `fetch`, non-OK
+ * status, broken stream), whose message is technical detail. A custom
+ * transport raises this for any user-facing upstream error text.
+ */
+export declare class StreamUpstreamError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Returns a renderable `Stage` for one raw payload: `index` defaults to `0`,
+ * `name` to `''`, an unrecognized `status` to `null` (still running), and
+ * `content`/`tag`/`attachments` are passed through when present.
+ */
+export declare const toStage: (stage: RawStage) => Stage;
 
 /** Request shape the host's selected-deployment recognition call accepts. */
 export declare interface TranscribeWithDeploymentParams {
@@ -728,8 +842,8 @@ export declare const useAttachmentUpload: ({ filesApi, bucket, onNetworkError, d
 
 /** Parameters for {@link useAttachmentUpload}. */
 export declare interface UseAttachmentUploadParams {
-    /** Already-configured generated-client instance used to upload the file. */
-    filesApi: Pick<FilesApi, 'uploadFile'>;
+    /** Already-configured client; optional listing skips stored names after a conflict. */
+    filesApi: Pick<FilesApi, 'uploadFile'> & Partial<Pick<FilesApi, 'listFiles'>>;
     /** DIAL Core bucket the file is uploaded into. */
     bucket: string | undefined;
     /** Called with batched filenames after a burst of network-error upload failures. */
@@ -938,7 +1052,7 @@ export declare interface UseConversationPanelItemsResolvers {
  * `transport`/`generation`/`channel`/`overlay` capabilities rather than any
  * app context or `server-api` import.
  */
-export declare const useConversationStream: ({ conversationId, state: { setConversation, conversationRef }, transport, generation: { startGeneration, completeGeneration }, channel, overlay, onStopError, generationConflictMessage, }: UseConversationStreamParams) => UseConversationStreamResult;
+export declare const useConversationStream: ({ conversationId, state: { setConversation, conversationRef }, transport, generation: { startGeneration, completeGeneration }, channel, overlay, onStopError, generationConflictMessage, onStreamError, }: UseConversationStreamParams) => UseConversationStreamResult;
 
 /** Parameters for {@link useConversationStream}. */
 export declare interface UseConversationStreamParams {
@@ -956,6 +1070,13 @@ export declare interface UseConversationStreamParams {
      * {@link DEFAULT_GENERATION_CONFLICT_MESSAGE}.
      */
     generationConflictMessage?: string;
+    /**
+     * Receives the original error of every failed stream. The hook shows only
+     * host-supplied or upstream-supplied text on the message bubble and hides
+     * transport detail (e.g. `Failed to fetch`), so this is where the host can
+     * still log or report the raw error.
+     */
+    onStreamError?: (error: Error) => void;
 }
 
 /** Return value of {@link useConversationStream}. */

package/conversation.js

@@ -1,31 +1,32 @@
 import { buildAnnouncementSignature as e, hasAnnouncementContent as t, hasStructuredAnnouncement as n, sanitizeAnnouncementHtml as r, sanitizeAnnouncementMessageHtml as i } from "./conversation/announcement-message.js";
-import { DEFAULT_GENERATION_CONFLICT_MESSAGE as a, GenerationConflictError as o, createChatStreamApi as s } from "./conversation/create-chat-stream-api.js";
-import { shouldWatchForDisplayNameUpdate as c } from "./conversation/display-name-watch.js";
-import { formatAppVersion as l, sanitizeFooterHtml as u } from "./conversation/footer-message.js";
-import { getModelIdFromConversationId as d } from "./conversation/get-model-id-from-conversation-id.js";
-import { getTimeOfDayGreeting as f } from "./conversation/greeting.js";
-import { createDeploymentChangedMessage as p } from "./conversation/message-factory.js";
-import { getLastDeploymentId as m, getLastUserMessageToolConfiguration as h, isMessageStreaming as g, messageHasStages as _, normalizeResponseFormat as v } from "./conversation/message-utils.js";
-import { toOverlayMessages as y } from "./conversation/overlay-messages.js";
+import { DEFAULT_GENERATION_CONFLICT_MESSAGE as a, GenerationConflictError as o, StreamUpstreamError as s, createChatStreamApi as c } from "./conversation/create-chat-stream-api.js";
+import { shouldWatchForDisplayNameUpdate as l } from "./conversation/display-name-watch.js";
+import { formatAppVersion as u, sanitizeFooterHtml as d } from "./conversation/footer-message.js";
+import { getModelIdFromConversationId as f } from "./conversation/get-model-id-from-conversation-id.js";
+import { getTimeOfDayGreeting as p } from "./conversation/greeting.js";
+import { createDeploymentChangedMessage as m } from "./conversation/message-factory.js";
+import { getLastDeploymentId as h, getLastUserMessageToolConfiguration as g, isMessageStreaming as _, messageHasStages as v, normalizeResponseFormat as y } from "./conversation/message-utils.js";
 import { getQuickAppConversationStarters as b } from "./conversation/quick-app-conversation-starters.js";
-import { getStarterPopulateText as x, getStartersFromSchema as S } from "./conversation/starter-option.js";
-import { deriveConversationRowActionState as C } from "./conversation/deriveConversationRowActionState/deriveConversationRowActionState.js";
-import { useActiveConversationSync as w } from "./conversation/useActiveConversationSync/useActiveConversationSync.js";
-import { useAsyncConfirmDialog as T } from "./conversation/useAsyncConfirmDialog/useAsyncConfirmDialog.js";
-import { useConversationLookupMaps as E } from "./conversation/useConversationLookupMaps/useConversationLookupMaps.js";
-import { getConversationSource as D, useConversationPanelItems as O } from "./conversation/useConversationPanelItems/useConversationPanelItems.js";
-import { useImportFilePicker as k } from "./conversation/useImportFilePicker/useImportFilePicker.js";
-import { useAttachmentUpload as A } from "./conversation/useAttachmentUpload/useAttachmentUpload.js";
-import { AudioTranscriptionError as j, AudioTranscriptionErrorReason as M } from "./conversation/useTranscribeAudio/audio-transcription-error.js";
-import { useTranscribeAudio as N } from "./conversation/useTranscribeAudio/useTranscribeAudio.js";
-import { attachmentToDto as P, attachmentsToDtos as F } from "./conversation/useConversationHandlers/attachment-to-dto.js";
-import { createMessagePair as I } from "./conversation/useConversationHandlers/message-factory.js";
-import { hasActiveToolConfig as L, isAnswerIncomplete as R, isMessageChanged as z, shouldRerunGenerationOnEdit as B } from "./conversation/useConversationHandlers/message-utils.js";
-import { getStarterConversationText as V, getStarterDisplayText as H, getStarterSubmitText as U } from "./conversation/useConversationHandlers/starter-option.js";
-import { getConversationPath as W } from "./conversation/useConversationStream/conversation-path.js";
-import { useConversationHandlers as G } from "./conversation/useConversationHandlers/useConversationHandlers.js";
-import { isAwaitingGenerationResume as K } from "./conversation/useConversationStream/generation-resume.js";
-import { useConversationStream as q } from "./conversation/useConversationStream/useConversationStream.js";
-import { useChatSettingsFormConfig as J } from "./useChatSettingsFormConfig/useChatSettingsFormConfig.js";
-import { useToolsMenu as Y } from "./useToolsMenu/useToolsMenu.js";
-export { j as AudioTranscriptionError, M as AudioTranscriptionErrorReason, a as DEFAULT_GENERATION_CONFLICT_MESSAGE, o as GenerationConflictError, P as attachmentToDto, F as attachmentsToDtos, e as buildAnnouncementSignature, s as createChatStreamApi, p as createDeploymentChangedMessage, I as createMessagePair, C as deriveConversationRowActionState, l as formatAppVersion, W as getConversationPath, D as getConversationSource, m as getLastDeploymentId, h as getLastUserMessageToolConfiguration, d as getModelIdFromConversationId, b as getQuickAppConversationStarters, V as getStarterConversationText, H as getStarterDisplayText, x as getStarterPopulateText, U as getStarterSubmitText, S as getStartersFromSchema, f as getTimeOfDayGreeting, L as hasActiveToolConfig, t as hasAnnouncementContent, n as hasStructuredAnnouncement, R as isAnswerIncomplete, K as isAwaitingGenerationResume, z as isMessageChanged, g as isMessageStreaming, _ as messageHasStages, v as normalizeResponseFormat, r as sanitizeAnnouncementHtml, i as sanitizeAnnouncementMessageHtml, u as sanitizeFooterHtml, B as shouldRerunGenerationOnEdit, c as shouldWatchForDisplayNameUpdate, y as toOverlayMessages, w as useActiveConversationSync, T as useAsyncConfirmDialog, A as useAttachmentUpload, J as useChatSettingsFormConfig, G as useConversationHandlers, E as useConversationLookupMaps, O as useConversationPanelItems, q as useConversationStream, k as useImportFilePicker, Y as useToolsMenu, N as useTranscribeAudio };
+import { mapStages as x, toStage as S } from "./conversation/stage.js";
+import { getStarterPopulateText as C, getStartersFromSchema as w } from "./conversation/starter-option.js";
+import { deriveConversationRowActionState as T } from "./conversation/deriveConversationRowActionState/deriveConversationRowActionState.js";
+import { useActiveConversationSync as E } from "./conversation/useActiveConversationSync/useActiveConversationSync.js";
+import { useAsyncConfirmDialog as D } from "./conversation/useAsyncConfirmDialog/useAsyncConfirmDialog.js";
+import { useConversationLookupMaps as O } from "./conversation/useConversationLookupMaps/useConversationLookupMaps.js";
+import { getConversationSource as k, useConversationPanelItems as A } from "./conversation/useConversationPanelItems/useConversationPanelItems.js";
+import { useImportFilePicker as j } from "./conversation/useImportFilePicker/useImportFilePicker.js";
+import { useAttachmentUpload as M } from "./conversation/useAttachmentUpload/useAttachmentUpload.js";
+import { AudioTranscriptionError as N, AudioTranscriptionErrorReason as P } from "./conversation/useTranscribeAudio/audio-transcription-error.js";
+import { useTranscribeAudio as F } from "./conversation/useTranscribeAudio/useTranscribeAudio.js";
+import { attachmentToDto as I, attachmentsToDtos as L } from "./conversation/useConversationHandlers/attachment-to-dto.js";
+import { createMessagePair as R } from "./conversation/useConversationHandlers/message-factory.js";
+import { hasActiveToolConfig as z, isAnswerIncomplete as B, isMessageChanged as V, shouldRerunGenerationOnEdit as H } from "./conversation/useConversationHandlers/message-utils.js";
+import { getStarterConversationText as U, getStarterDisplayText as W, getStarterSubmitText as G } from "./conversation/useConversationHandlers/starter-option.js";
+import { getConversationPath as K } from "./conversation/useConversationStream/conversation-path.js";
+import { useConversationHandlers as q } from "./conversation/useConversationHandlers/useConversationHandlers.js";
+import { applyChunkToMessages as J, mergeStages as Y } from "./conversation/useConversationStream/apply-chunk.js";
+import { isAwaitingGenerationResume as X } from "./conversation/useConversationStream/generation-resume.js";
+import { useConversationStream as Z } from "./conversation/useConversationStream/useConversationStream.js";
+import { useChatSettingsFormConfig as Q } from "./useChatSettingsFormConfig/useChatSettingsFormConfig.js";
+import { useToolsMenu as $ } from "./useToolsMenu/useToolsMenu.js";
+export { N as AudioTranscriptionError, P as AudioTranscriptionErrorReason, a as DEFAULT_GENERATION_CONFLICT_MESSAGE, o as GenerationConflictError, s as StreamUpstreamError, J as applyChunkToMessages, I as attachmentToDto, L as attachmentsToDtos, e as buildAnnouncementSignature, c as createChatStreamApi, m as createDeploymentChangedMessage, R as createMessagePair, T as deriveConversationRowActionState, u as formatAppVersion, K as getConversationPath, k as getConversationSource, h as getLastDeploymentId, g as getLastUserMessageToolConfiguration, f as getModelIdFromConversationId, b as getQuickAppConversationStarters, U as getStarterConversationText, W as getStarterDisplayText, C as getStarterPopulateText, G as getStarterSubmitText, w as getStartersFromSchema, p as getTimeOfDayGreeting, z as hasActiveToolConfig, t as hasAnnouncementContent, n as hasStructuredAnnouncement, B as isAnswerIncomplete, X as isAwaitingGenerationResume, V as isMessageChanged, _ as isMessageStreaming, x as mapStages, Y as mergeStages, v as messageHasStages, y as normalizeResponseFormat, r as sanitizeAnnouncementHtml, i as sanitizeAnnouncementMessageHtml, d as sanitizeFooterHtml, H as shouldRerunGenerationOnEdit, l as shouldWatchForDisplayNameUpdate, S as toStage, E as useActiveConversationSync, D as useAsyncConfirmDialog, M as useAttachmentUpload, Q as useChatSettingsFormConfig, q as useConversationHandlers, O as useConversationLookupMaps, A as useConversationPanelItems, Z as useConversationStream, j as useImportFilePicker, $ as useToolsMenu, F as useTranscribeAudio };