@epam/ai-dial-chat-hooks 1.2.0-dev.6 → 1.2.0-dev.61

package/index.d.ts

@@ -1,5 +1,6 @@
 import { Annotation } from '@epam/ai-dial-chat-shared';
 import { AnnotationGroup } from '@epam/ai-dial-quotations';
+import { ApplicationVisualizer } from '@epam/ai-dial-chat-shared';
 import { ArchiveItemDto } from '@epam/ai-dial-chat-api-client';
 import { Attachment } from '@epam/ai-dial-chat-shared';
 import { AttachmentDisplayResolvers } from '@epam/ai-dial-chat-shared';
@@ -69,6 +70,7 @@ import { FileUploadStatus } from '@epam/ai-dial-chat-shared';
 import { FileUploadValidationResult } from '@epam/ai-dial-chat-shared';
 import { FilterTab } from '@epam/ai-dial-chat-shared';
 import { getParentFolderPath } from '@epam/ai-dial-chat-shared';
+import type { GroupedAttachmentItem } from '@epam/ai-dial-chat-shared';
 import type { InputHighlightData } from '@epam/pdf-highlighter-kit';
 import { ListFilesItemDto } from '@epam/ai-dial-chat-api-client';
 import { ListFilesResponseDto } from '@epam/ai-dial-chat-api-client';
@@ -127,6 +129,7 @@ import { SkillFileUploadCandidate } from '@epam/ai-dial-skill-editor';
 import { SkillFileValidationResult } from '@epam/ai-dial-skill-editor';
 import { SkillMetadataItemDto } from '@epam/ai-dial-chat-api-client';
 import { SkillUploadResponseDto } from '@epam/ai-dial-chat-api-client';
+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';
@@ -247,6 +250,25 @@ export declare interface ApiErrorDetails {
 /** Appends a locale's uppercased code to a field label, e.g. `'Name [EN]'`. */
 export declare const appendLocaleCode: (label: string, locale: string) => 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;
+
 /** Converts an APScheduler weekday (Monday=0..Sunday=6) to a JS `Date` weekday (Sunday=0..Saturday=6). */
 export declare const apSchedulerDayToJsDay: (apSchedulerDay: number) => number;
 
@@ -314,6 +336,7 @@ declare enum AttachmentContentType {
     Code = 'code',
     Html = 'html',
     Visualizer = 'visualizer',
+    GroupedVisualizer = 'grouped_visualizer',
     McpApp = 'mcp_app',
     Unsupported = 'unsupported',
     Error = 'error',
@@ -522,6 +545,13 @@ export declare const buildSkillManifestFromFrontmatter: (baseFrontmatter: Record
  * authored it, when it last changed, and its file inventory. Grouping folders
  * in the file listing are excluded from both the count and the rows. Sizes are
  * not shown — the skill metadata carries no content-length field.
+ *
+ * `skill` is the authoritative `getSkillMetadata` response when that request
+ * fulfilled; the caller falls back to the catalog listing entry only when it
+ * rejected (`useSkillItemDetails`'s `onFetchSkillDetails`). Either way, this
+ * function never fills a gap in one source from the other — an absent
+ * `author` omits the row and an absent `updatedAt` leaves the updated row's
+ * value empty, exactly as `skill` carries it.
  */
 export declare const buildSkillOverview: (skill: SkillMetadataItemDto | undefined, files: SkillMetadataItemDto[], about: SkillAboutDetails | undefined, labels: SkillOverviewLabels) => CatalogItemOverview;
 
@@ -1838,6 +1868,30 @@ export declare interface GreetingTranslations {
     nightNoName: string;
 }
 
+/** Content payload for an application-scoped grouped visualizer: every attachment a message's visualizer claims, rendered together inside one sandboxed iframe. */
+declare interface GroupedVisualizerCanvasContent {
+    /** Discriminates the content type to select the correct renderer. */
+    type: AttachmentContentType.GroupedVisualizer;
+    /** Iframe `src`, resolved from the matching registry entry's `url`. */
+    url: string;
+    /** One item per claimed attachment, in the message's attachment order. Each `url` is absolute, resolved by the host. */
+    attachments: GroupedAttachmentItem[];
+    /** Presentation layout hints (`themeId`, `width`, `height`, `mobileHeight`) shared by every item. */
+    layout: CustomVisualizerDataLayout;
+    /** postMessage protocol namespace — MUST equal the registry entry's `title`, or the iframe never receives data. */
+    visualizerName: string;
+    /** Milliseconds to wait for a `send()` request's response before rejecting. From the registry entry; does NOT bound the handshake. */
+    requestTimeout?: number;
+}
+
+/** Outcome of building a grouped visualizer payload. */
+export declare interface GroupedVisualizerResolution {
+    /** The grouped payload, or `null` when no claimed attachment resolved to a URL. */
+    content: GroupedVisualizerCanvasContent | null;
+    /** The claimed attachments that reached `content.attachments`, in the input's order. The caller returns the rest to the ordinary attachment tray. */
+    resolved: DisplayAttachment[];
+}
+
 /** Whether at least one tool toggle in `value` is active. */
 export declare const hasActiveToolConfig: (value: Record<string, boolean> | undefined) => boolean;
 
@@ -2174,6 +2228,13 @@ export declare interface MapSkillToCatalogItemOptions {
     favoriteIds: ReadonlySet<string>;
 }
 
+/**
+ * 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;
+
 /**
  * Maps a toolset's specification into the lib's credential-status shape,
  * for refreshing the details panel after login/logout. Includes both
@@ -2356,6 +2417,22 @@ export declare enum McpResourceKind {
 
 export declare const mergeCreatedFolderIntoCache: (cache: Map<string, ListFilesItemDto[]>, parentApiPath: string, created: CreateFolderResponseDto, inheritedPermissions?: string[]) => Map<string, ListFilesItemDto[]>;
 
+/**
+ * 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;
 
@@ -2544,7 +2621,17 @@ declare interface OoxmlDocxHighlightLocation {
     text: string;
 }
 
-/** Supported document formats rendered by the bundled `@silurus/ooxml` runtime. */
+/** A complete table row in the DOCX body, matched by cell text. */
+declare interface OoxmlDocxTableRowLocation {
+    /** Location kind. */
+    kind: OoxmlHighlightKind.DocxTableRow;
+    /** Plain text of each cell, in column order. */
+    cells: string[];
+    /** 1-based matching row in document order. */
+    occurrence: number;
+}
+
+/** Supported document formats rendered by the installed `@silurus/ooxml` runtime. */
 declare enum OoxmlFileType {
     Docx = 'docx',
     Xlsx = 'xlsx',
@@ -2566,6 +2653,10 @@ declare enum OoxmlHighlightKind {
     DocxTextRange = 'docxTextRange',
     /** A character range inside a single PPTX shape on one slide. */
     PptxTextRange = 'pptxTextRange',
+    /** A complete DOCX table row identified by its cell text. */
+    DocxTableRow = 'docxTableRow',
+    /** A complete PPTX table row identified by its cell text on one slide. */
+    PptxTableRow = 'pptxTableRow',
     /** One cell, or a contiguous same-row cell range, on a named XLSX sheet. */
     XlsxCellRange = 'xlsxCellRange',
 }
@@ -2574,6 +2665,8 @@ declare enum OoxmlHighlightKind {
 declare type OoxmlHighlightLocation =
 | OoxmlDocxHighlightLocation
 | OoxmlPptxHighlightLocation
+| OoxmlDocxTableRowLocation
+| OoxmlPptxTableRowLocation
 | OoxmlXlsxHighlightLocation;
 
 /** A cited character range inside a single shape on one PPTX slide. */
@@ -2592,6 +2685,18 @@ declare interface OoxmlPptxHighlightLocation {
     text: string;
 }
 
+/** A complete table row on one PPTX slide, matched by cell text. */
+declare interface OoxmlPptxTableRowLocation {
+    /** Location kind. */
+    kind: OoxmlHighlightKind.PptxTableRow;
+    /** Plain text of each cell, in column order. */
+    cells: string[];
+    /** 1-based matching row on the specified slide. */
+    occurrence: number;
+    /** 1-based slide number. */
+    slide: number;
+}
+
 /** A cited cell, or contiguous same-row cell range, on a named XLSX sheet. */
 declare interface OoxmlXlsxHighlightLocation {
     /** Discriminates this location within `OoxmlHighlightLocation`. */
@@ -2846,6 +2951,63 @@ export declare interface QuickAppSchemaLike {
     displayName?: string;
 }
 
+/**
+ * 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;
+}
+
 /**
  * Reads a skill file response as raw bytes, or `null` when the body is
  * larger than `SKILL_MANIFEST_MAX_BYTES`. The declared `content-length` is
@@ -2856,6 +3018,24 @@ export declare interface QuickAppSchemaLike {
  */
 export declare const readSkillFileBytes: (response: Response) => Promise<Uint8Array | null>;
 
+/**
+ * Reads a skill file response as raw bytes with no size ceiling, for the
+ * supporting-file **preview** path.
+ *
+ * Previews are user-initiated, one file at a time, and a realistic binary
+ * (a PDF, an image) routinely exceeds `SKILL_MANIFEST_MAX_BYTES` — a cap
+ * sized for `SKILL.md` frontmatter, not for binaries — so applying that cap
+ * here rejected virtually every real PDF before it was ever decoded. This
+ * reader therefore never returns `null`: file size is not a failure class on
+ * the preview path.
+ *
+ * `readSkillFileBytes` and `readSkillManifest` keep their
+ * `SKILL_MANIFEST_MAX_BYTES` ceiling, because they feed the manifest parse
+ * and the textual Content-tab read, where an oversized body must never be
+ * decoded into a string.
+ */
+export declare const readSkillFilePreviewBytes: (response: Response) => Promise<Uint8Array>;
+
 /**
  * Reads a skill manifest response as text, or `null` when the body is larger
  * than `SKILL_MANIFEST_MAX_BYTES`. The size is checked before decoding, so an
@@ -2920,7 +3100,8 @@ export declare const resolveCatalogPrimaryAction: (item: CatalogItem, fetchPromp
 /** Resolves a syntax-highlighted code canvas content payload from a DisplayAttachment, or `null` if unavailable. */
 export declare const resolveCodeCanvasContent: (attachment: DisplayAttachment, resolvers: AttachmentCanvasUrlResolvers, language?: string) => Promise<CodeCanvasContent | ErrorCanvasContent | null>;
 
-export declare const resolveDeploymentFolder: (deployment: Pick<DeploymentItemDto, "isMy" | "sharedWithMe" | "applicationFolder">, labels: DeploymentFolderLabels) => string[];
+/** Resolves a deployment's display folder, including organization applications without a folder path. */
+export declare const resolveDeploymentFolder: (deployment: Pick<DeploymentItemDto, "isMy" | "sharedWithMe" | "applicationFolder"> & Partial<Pick<DeploymentItemDto, "type">>, labels: DeploymentFolderLabels) => string[];
 
 /**
  * Resolves a DialFile to the bucket-relative API path used by files BFF endpoints.
@@ -2956,6 +3137,17 @@ export declare type ResolveDownloadUrl = (fileId: string) => string | undefined;
  */
 export declare const resolveExternalSourceContentType: (contentType: string, url: string) => string;
 
+/**
+ * Builds the grouped payload for an application-scoped visualizer from the
+ * attachments its entry claims, reporting which of them `resolveAbsoluteUrl`
+ * could produce a URL for. Unlike the single-attachment resolver this fetches
+ * nothing: the grouped protocol hands the visualizer URLs and lets it read
+ * them itself, so the URLs must be absolute — a host-relative path would
+ * resolve against the iframe's own origin. Producing one is host knowledge,
+ * which is why it arrives as a callback rather than being built here.
+ */
+export declare const resolveGroupedVisualizerCanvasContent: (attachments: DisplayAttachment[], resolveAbsoluteUrl: (attachment: DisplayAttachment) => string | undefined, entry: ApplicationVisualizer, themeId: string) => GroupedVisualizerResolution;
+
 /**
  * Resolves an HTML canvas content payload from a DisplayAttachment.
  * Fetches and inlines the HTML as `srcdoc` when the attachment has a download URL or inline data.
@@ -2966,10 +3158,12 @@ export declare const resolveHtmlCanvasContent: (attachment: DisplayAttachment, r
 
 /**
  * Resolves an image canvas content payload from a DisplayAttachment without
- * fetching — returns the BFF download URL (or a local/inline blob URL)
- * directly so the browser cache can be shared with the conversation view's
- * `<img>` element. Error detection is delegated to `<img onError>` in the
- * canvas renderer. Returns `null` if no URL source is available.
+ * fetching — returns a local blob URL or the BFF download URL directly so the
+ * browser cache can be shared with the conversation view's `<img>` element.
+ * A local `File` with bytes takes precedence over the DIAL download URL; a
+ * 0-byte `File` (the file-manager placeholder) does not. Error detection is
+ * delegated to `<img onError>` in the canvas renderer. Returns `null` if no
+ * URL source is available.
  */
 export declare const resolveImageCanvasContent: (attachment: DisplayAttachment, resolvers: AttachmentCanvasUrlResolvers) => ImageCanvasContent | null;
 
@@ -3175,6 +3369,12 @@ export declare interface SkillDetailsApi {
         limit?: number;
         recursive?: boolean;
     }, signal?: AbortSignal): Promise<SkillFileListResponseDto>;
+    /**
+     * Fetches a single skill's own authoritative metadata (`author`,
+     * `updatedAt`, and the rest of `SkillMetadataItemDto`) — not the catalog
+     * listing entry, which may be sparse for a shared skill.
+     */
+    getSkillMetadata(bucket: string, path: string, signal?: AbortSignal): Promise<SkillMetadataItemDto>;
 }
 
 /** Already-configured DIAL Core download operations `useSkillEditorLoad` needs. */
@@ -3749,6 +3949,13 @@ export declare const toPublishEntityType: (type: CatalogEntityType) => CatalogPu
  */
 export declare const toPublishRuleDto: (rule: PublicationRule) => PublishRuleDto;
 
+/**
+ * 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 {
     audioUrl: string;
@@ -3891,8 +4098,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. */
@@ -5473,10 +5680,11 @@ export declare interface UseSkillFilePreviewResult {
 
 /**
  * Headless hook that encapsulates skill detail fetching: manifest download and
- * parse, package file listing, overview construction, and in-package file
- * loads. `useCatalogItemDetails` delegates its skill branch here; hosts that
- * only surface skill details consume this hook directly, without the
- * deployment and prompt ports the full catalog pipeline requires.
+ * parse, package file listing, authoritative metadata fetching, overview
+ * construction, and in-package file loads. `useCatalogItemDetails` delegates
+ * its skill branch here; hosts that only surface skill details consume this
+ * hook directly, without the deployment and prompt ports the full catalog
+ * pipeline requires.
  */
 export declare const useSkillItemDetails: ({ api, skills, skillOverviewLabels, }: UseSkillItemDetailsOptions) => UseSkillItemDetailsResult;