@epam/ai-dial-chat-hooks 1.2.0-dev.1 → 1.2.0-dev.102

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';
@@ -36,8 +36,47 @@ export declare interface AnnouncementContent {
     title: string | null;
     description: string | null;
     html: string | null;
+    /** Entries of the popover the banner opens. */
+    items?: readonly AnnouncementListItem[];
 }
 
+/** One entry of the announcements popover behind the banner's `+N` pill. */
+export declare interface AnnouncementListItem {
+    /** Plain-text heading of the entry. */
+    title: string;
+    /** Supporting copy of the entry, sanitized before it is rendered. */
+    description?: string | null;
+    /** Optional call to action shown at the end of the entry. */
+    link?: AnnouncementListItemLink | null;
+}
+
+/** A link rendered as the call to action of an announcements-popover entry. */
+export declare interface AnnouncementListItemLink {
+    /** Visible text of the call to action. */
+    label: string;
+    /** Absolute `http`/`https` target the call to action opens. */
+    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> {
     /**
@@ -95,7 +134,7 @@ export declare enum AudioTranscriptionErrorReason {
     Unavailable = "unavailable",
     /** The recording exceeds the caller's configured size limit. */
     TooLarge = "tooLarge",
-    /** The upstream ASR provider stayed rate-limited or unavailable after retrying. */
+    /** Recognition is rate-limited, unavailable, or exhausted short gateway retries. */
     Busy = "busy",
     /** Recognition failed for any other reason. */
     Failed = "failed"
@@ -107,9 +146,18 @@ export declare enum AudioTranscriptionErrorReason {
  * hidden only while the current announcement produces the same signature, so
  * editing any part of it brings the banner back with no version counter.
  *
+ * Every piece of content the banner surface renders feeds the signature — the
+ * title, the description, and the popover entries behind the pill, which live
+ * inside the banner and are hidden along with it. Publishing a new entry in
+ * that list therefore invalidates an earlier dismissal on its own, even when
+ * the banner line itself is untouched.
+ *
  * A legacy-only announcement returns the raw HTML string — byte-identical to
  * what shipped before the structured fields existed — so dismissals recorded
- * by older builds keep working without a storage migration.
+ * by older builds keep working without a storage migration. `items` is left
+ * out of the payload entirely when the list is empty for the same reason: a
+ * deployment that never configured the popover keeps matching the signatures
+ * its users already have stored.
  */
 export declare const buildAnnouncementSignature: (content: AnnouncementContent) => string;
 
@@ -544,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;
 
@@ -577,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. */
@@ -633,8 +761,12 @@ 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[];
+/**
+ * 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 {
@@ -699,8 +831,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. */

package/conversation.js

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