@epam/ai-dial-chat-hooks 1.1.0-dev.422 → 1.1.0-dev.426

package/files/useDialFileMutations/useDialFileMutations.js

@@ -0,0 +1,359 @@
+import { FileManagerNotificationReason as e, FileNameValidationErrorReason as t, FileOperationKind as n } from "../dial-file-manager.types.js";
+import { RESERVED_MARKER_NAME as r } from "../dial-file-manager.model.js";
+import { formatOperationFolderName as i, getVirtualPathName as a, hasForbiddenNameSymbols as o, parseNewFolderVirtualPath as s, resolveOwnerCoords as c } from "../dial-file-manager-path.util.js";
+import { getParentFolderPath as l, resolveDialFileApiPath as u, virtualPathToApiPath as d } from "../resolve-dial-file-api-path.js";
+import { prepareCopyItems as f, prepareMoveRenameItems as p } from "../dial-file-manager-copy-move.util.js";
+import { findFirstSuccessfulCopyMoveItem as m } from "../dial-file-manager-mapping.util.js";
+import { DownloadDestinationType as h } from "../download-destination.js";
+import { useCallback as g, useRef as _, useState as v } from "react";
+import { ArchiveItemDtoNodeTypeEnum as y, DeleteItemDtoNodeTypeEnum as b, RenameItemDtoNodeTypeEnum as x } from "@epam/ai-dial-chat-api-client";
+import { NOT_ALLOWED_SYMBOLS as S, NotificationVariant as C } from "@epam/ai-dial-ui-kit";
+import { DialFileManagerTabs as w, DialFileNodeType as T } from "@epam/ai-dial-react-file-manager";
+//#region src/files/useDialFileMutations/useDialFileMutations.ts
+var E = ({ filesApi: E, bucket: D, rootLabel: O, activeTab: k, folderPath: A, currentFolder: j, sharedRootMetaRef: M, listingPermissionsCache: N, invalidateFolders: P, bumpRetry: F, mergeCreatedFolder: I, setFolderPath: L, onNotification: R, onOperationSuccess: z, downloadDestination: B, forbiddenSymbolsRegExp: V }) => {
+	let [ee, H] = v(!1), [te, U] = v(!1), [ne, W] = v(!1), [G, K] = v(!1), [q, J] = v(!1), [Y, X] = v(!1), Z = _(null), Q = _(null), $ = g((e, n) => {
+		let i = null;
+		if (!e || e.trim() === "") i = { reason: t.Empty };
+		else if (o(e, V)) i = {
+			reason: t.ForbiddenSymbols,
+			symbols: S
+		};
+		else if (e.startsWith(".")) i = { reason: t.LeadingDot };
+		else if (e === r) i = { reason: t.ReservedName };
+		else if (e.length > 255) i = {
+			reason: t.TooLong,
+			maxLength: 255
+		};
+		else {
+			let r = n.items ?? [], a = e.toLowerCase(), o = r.find((e) => e.name.toLowerCase() === a);
+			o && (i = {
+				reason: t.DuplicateName,
+				existingName: o.name
+			});
+		}
+		return Q.current = i, i;
+	}, [V]), re = g(async (t, r, i) => {
+		let { parentVirtualPath: a, name: o } = s(r, O), l = d(a, O), u = j && A === l ? j : {
+			id: l,
+			path: l,
+			name: a.split("/").filter(Boolean).pop() ?? "",
+			folderId: l,
+			nodeType: T.FOLDER,
+			items: []
+		}, f = Q.current;
+		if (Q.current = null, $(o, u) || f) return;
+		H(!0);
+		let { bucket: p, path: m } = k === w.Shared ? c(l, M.current, D) : {
+			bucket: D,
+			path: l
+		};
+		try {
+			I(l, await E.createFolder({
+				bucket: p,
+				parentPath: m,
+				name: o
+			}), N.get(l)), F(), z?.({
+				kind: n.FolderCreated,
+				name: o
+			});
+		} catch {
+			R?.({
+				variant: C.Error,
+				reason: e.FolderCreateFailed
+			});
+		} finally {
+			H(!1);
+		}
+	}, [
+		k,
+		D,
+		j,
+		E,
+		A,
+		$,
+		O,
+		N,
+		I,
+		F,
+		z,
+		M,
+		R
+	]), ie = g((t) => {
+		(async () => {
+			U(!0);
+			try {
+				let e = t.length === 1 ? t[0].nodeType === T.ITEM ? t[0].name : `${t[0].name}.zip` : "files.zip", r = await B.resolveDestination(e, t.length === 1 && t[0].nodeType === T.ITEM ? t[0].contentType ?? "application/octet-stream" : "application/zip");
+				if (r.type === h.Cancelled) return;
+				if (t.length === 1 && t[0].nodeType === T.ITEM) {
+					let e = t[0];
+					if (!e.bucket) throw Error("File is missing bucket");
+					let i = u(e, e.bucket, O), a = await E.downloadFile(e.bucket, i);
+					if (!a.ok) throw Error(`Download failed with status ${a.status}`);
+					let o = await B.triggerDownload(a, e.name, r);
+					z?.({
+						kind: n.FileDownloaded,
+						name: o,
+						count: 1
+					});
+				} else {
+					let i = t.map((e) => ({
+						bucket: e.bucket ?? D,
+						path: u(e, e.bucket ?? D, O),
+						name: e.name,
+						nodeType: e.nodeType === T.FOLDER ? y.Folder : y.Item
+					})), a = await E.downloadArchive(i);
+					if (!a.ok) throw Error(`Download failed with status ${a.status}`);
+					let o = await B.triggerDownload(a, e, r);
+					t.length === 1 ? z?.({
+						kind: n.FileDownloaded,
+						name: o
+					}) : z?.({
+						kind: n.FilesDownloaded,
+						count: t.length
+					});
+				}
+			} catch {
+				R?.({
+					variant: C.Error,
+					reason: t.length === 1 ? e.DownloadFileFailed : e.DownloadFilesFailed
+				});
+			} finally {
+				U(!1);
+			}
+		})();
+	}, [
+		D,
+		O,
+		z,
+		R,
+		E,
+		B
+	]), ae = g((t, n) => {
+		t.length !== 0 && (async () => {
+			W(!0);
+			let r = t.map((e) => {
+				let t = e.nodeType === T.FOLDER, n = d(e.sourceUrl, O), r = t ? n : n.replace(/\/$/, ""), i = a(e.sourceUrl, r), { bucket: o, path: s } = k === w.Shared ? c(r, M.current, D) : {
+					bucket: D,
+					path: r
+				};
+				return {
+					bucket: o,
+					path: s,
+					name: i,
+					nodeType: t ? b.Folder : b.Item
+				};
+			});
+			try {
+				let { results: t } = await E.deleteFiles(r), i = t.filter((e) => !e.success), a = i.length, o = t.length - a, s = t.find((e) => e.success), c = r.find((e) => e.path === s?.path) ?? r[0];
+				if (o > 0 && R?.({
+					variant: C.Success,
+					reason: e.FilesDeleted,
+					count: o,
+					name: c?.name,
+					folder: n || O
+				}), a > 0) {
+					let t = i.slice(0, 3).map((e) => r.find((t) => t.path === e.path)?.name ?? e.path), n = a - t.length;
+					R?.({
+						variant: C.Error,
+						reason: e.FilesDeletePartiallyFailed,
+						names: t,
+						restCount: n
+					});
+				}
+			} catch {
+				R?.({
+					variant: C.Error,
+					reason: e.DeleteFailed
+				});
+			}
+			let i = r.filter((e) => e.nodeType === b.Folder).map((e) => e.path.endsWith("/") ? e.path : `${e.path}/`);
+			P([...new Set(r.map((e) => {
+				if (e.nodeType === b.Folder) return e.path.endsWith("/") ? e.path : `${e.path}/`;
+				let t = e.path.lastIndexOf("/");
+				return t > 0 ? e.path.slice(0, t + 1) : "";
+			}))]), i.some((e) => A === e || A.startsWith(e)) && L((e) => e.replace(/[^/]+\/$/, "")), F(), W(!1);
+		})();
+	}, [
+		k,
+		D,
+		O,
+		A,
+		R,
+		E,
+		M,
+		P,
+		F,
+		L
+	]), oe = g((e, n) => {
+		if (!e || e.trim() === "") return { reason: t.Empty };
+		if (e === r) return { reason: t.ReservedName };
+		if (o(e, V)) return {
+			reason: t.ForbiddenSymbols,
+			symbols: S
+		};
+		if (e.length > 255) return {
+			reason: t.TooLong,
+			maxLength: 255
+		};
+		let i = j?.items ?? [], a = e.toLowerCase(), s = i.find((e) => e.path !== n.path && e.name.toLowerCase() === a);
+		return s ? {
+			reason: t.DuplicateName,
+			existingName: s.name
+		} : null;
+	}, [V, j]), se = g((t, r) => {
+		if (t.length === 0 || q || Y) return;
+		let a = new AbortController();
+		Z.current = a, (async () => {
+			J(!0);
+			let o = f(t, D, O), s = o.map(({ dto: e }) => e);
+			try {
+				let { results: t } = await E.copyFiles(s, a.signal), c = t.filter((e) => !e.success).length, l = t.length - c;
+				if (l > 0) {
+					let e = m(o, t);
+					z?.({
+						kind: l === 1 ? n.FileCopied : n.FilesCopied,
+						name: e?.destinationName,
+						count: l,
+						destinationFolderName: i(r, O)
+					});
+				}
+				c > 0 && c < t.length ? R?.({
+					variant: C.Error,
+					reason: e.CopyPartiallyFailed,
+					count: c
+				}) : c === t.length && R?.({
+					variant: C.Error,
+					reason: e.CopyFailed
+				});
+			} catch {
+				a.signal.aborted || R?.({
+					variant: C.Error,
+					reason: e.CopyFailed
+				});
+			} finally {
+				P([...new Set(s.flatMap((e) => [l(e.sourcePath), l(e.destinationPath)]))]), F(), J(!1), Z.current = null;
+			}
+		})();
+	}, [
+		D,
+		O,
+		R,
+		z,
+		E,
+		q,
+		Y,
+		P,
+		F
+	]), ce = g(() => {
+		Z.current?.abort();
+	}, []);
+	return {
+		isCreatingFolder: ee,
+		isDownloading: te,
+		isDeleting: ne,
+		isRenaming: G,
+		isCopying: q,
+		isMoving: Y,
+		onCreateFolder: re,
+		onCreateFolderValidate: $,
+		onDownloadFiles: ie,
+		onDeleteFiles: ae,
+		onRenameValidate: oe,
+		onMoveToFiles: g((t, r, o) => {
+			if (t.length === 0 || q || Y || G) return;
+			let { renameDtos: s, preparedMoveItems: c } = p(t, D, O), u = c.map(({ dto: e }) => e), d = new AbortController();
+			u.length > 0 && (Z.current = d), (async () => {
+				s.length > 0 && K(!0), u.length > 0 && X(!0);
+				let [t, r] = await Promise.all([(async () => {
+					if (s.length === 0) return {
+						results: [],
+						threw: !1
+					};
+					try {
+						let { results: e } = await E.renameFiles(s);
+						return {
+							results: e,
+							threw: !1
+						};
+					} catch {
+						return {
+							results: [],
+							threw: !0
+						};
+					}
+				})(), (async () => {
+					if (u.length === 0) return {
+						results: [],
+						threw: !1,
+						aborted: !1
+					};
+					try {
+						let { results: e } = await E.moveFiles(u, d.signal);
+						return {
+							results: e,
+							threw: !1,
+							aborted: !1
+						};
+					} catch {
+						return {
+							results: [],
+							threw: !0,
+							aborted: d.signal.aborted
+						};
+					}
+				})()]), f = t.threw ? s.length : t.results.filter((e) => !e.success).length, p = r.threw && r.aborted, h = p ? 0 : u.length, g = p ? 0 : r.threw ? u.length : r.results.filter((e) => !e.success).length, _ = r.threw ? 0 : r.results.filter((e) => e.success).length, v = s.length + h, y = f + g, b = g > 0;
+				if (_ > 0) {
+					let e = m(c, r.results);
+					z?.({
+						kind: _ === 1 ? n.FileMoved : n.FilesMoved,
+						name: e?.destinationName,
+						count: _,
+						destinationFolderName: i(o, O)
+					});
+				}
+				if (s.length === 1 && f === 0) {
+					let [e] = s;
+					z?.({
+						kind: n.FileRenamed,
+						name: a(e.destinationPath, e.destinationPath),
+						isFolder: e.nodeType === x.Folder
+					});
+				}
+				y > 0 && (y === v ? R?.({
+					variant: C.Error,
+					reason: b ? e.MoveFailed : e.RenameFailed
+				}) : R?.({
+					variant: C.Error,
+					reason: b ? e.MovePartiallyFailed : e.RenamePartiallyFailed,
+					count: y
+				}));
+				let S = s.find((e) => e.nodeType === x.Folder && t.results.some((t) => t.success && t.sourcePath === e.sourcePath));
+				if (S != null) {
+					let e = S.sourcePath.endsWith("/") ? S.sourcePath : `${S.sourcePath}/`;
+					if (A === e || A.startsWith(e)) {
+						let t = S.destinationPath.endsWith("/") ? S.destinationPath : `${S.destinationPath}/`;
+						L(A.replace(e, t));
+					}
+				}
+				P([...new Set([...s, ...u].flatMap((e) => [l(e.sourcePath), l(e.destinationPath)]))]), F(), K(!1), X(!1), u.length > 0 && (Z.current = null);
+			})();
+		}, [
+			D,
+			O,
+			A,
+			z,
+			R,
+			E,
+			q,
+			Y,
+			G,
+			P,
+			F,
+			L
+		]),
+		onCopyFiles: se,
+		cancelCopyMove: ce
+	};
+};
+//#endregion
+export { E as useDialFileMutations };

package/files/useDialFileSharing/useDialFileSharing.js

@@ -0,0 +1,70 @@
+import { FileManagerNotificationReason as e } from "../dial-file-manager.types.js";
+import { resolveDialFileApiPath as t } from "../resolve-dial-file-api-path.js";
+import { useCallback as n, useState as r } from "react";
+import { NotificationVariant as i } from "@epam/ai-dial-ui-kit";
+//#region src/files/useDialFileSharing/useDialFileSharing.ts
+var a = ({ filesApi: a, bucket: o, rootLabel: s, bumpRetry: c, onNotification: l }) => {
+	let [u, d] = r(!1), [f, p] = r(!1);
+	return {
+		isUnsharing: u,
+		isRemovingAccess: f,
+		onUnshareFiles: n((n) => {
+			n.length !== 0 && (async () => {
+				d(!0);
+				let r = n.map((e) => {
+					let n = e.bucket ?? o;
+					return {
+						bucket: n,
+						path: t(e, n, s)
+					};
+				});
+				try {
+					await a.discardShared(r), c();
+				} catch {
+					l?.({
+						variant: i.Error,
+						reason: e.UnshareFailed
+					});
+				} finally {
+					d(!1);
+				}
+			})();
+		}, [
+			o,
+			s,
+			l,
+			a,
+			c
+		]),
+		onRemoveFilesAccess: n((n) => {
+			n.length !== 0 && (async () => {
+				p(!0);
+				let r = n.map((e) => {
+					let n = e.bucket ?? o;
+					return {
+						bucket: n,
+						path: t(e, n, s)
+					};
+				});
+				try {
+					await a.revokeAccess(r), c();
+				} catch {
+					l?.({
+						variant: i.Error,
+						reason: e.RemoveAccessFailed
+					});
+				} finally {
+					p(!1);
+				}
+			})();
+		}, [
+			o,
+			s,
+			l,
+			a,
+			c
+		])
+	};
+};
+//#endregion
+export { a as useDialFileSharing };

package/files/useDialFileUploadBatch/useDialFileUploadBatch.js

@@ -0,0 +1,156 @@
+import { DialFilesApiUploadMode as e } from "../dial-files-api.js";
+import { FileManagerNotificationReason as t } from "../dial-file-manager.types.js";
+import "../dial-file-manager.model.js";
+import { resolveOwnerCoords as n } from "../dial-file-manager-path.util.js";
+import { virtualPathToApiPath as r } from "../resolve-dial-file-api-path.js";
+import { updateEntry as i } from "../dial-file-manager-mapping.util.js";
+import { sanitizeFileName as a } from "../file-name.js";
+import { FileUploadStatus as o } from "@epam/ai-dial-chat-shared";
+import { useCallback as s, useRef as c, useState as l } from "react";
+import { NotificationVariant as u } from "@epam/ai-dial-ui-kit";
+import { DialFileManagerTabs as d } from "@epam/ai-dial-react-file-manager";
+//#region src/files/useDialFileUploadBatch/useDialFileUploadBatch.ts
+var f = 5, p = (e) => e.error ? `${e.path} (${e.error})` : e.path, m = (e) => {
+	let t = e.slice(0, f);
+	return {
+		names: t.map(p),
+		restCount: e.length - t.length
+	};
+}, h = (e, t) => `${e}${t}/`, g = (e) => /\.zip$/i.test(e), _ = (e) => {
+	let [t] = e;
+	if (!(e.length !== 1 || t == null)) return g(t.fileContent.name) && !g(t.name) ? t : void 0;
+}, v = ({ filesApi: f, bucket: p, rootLabel: g, activeTab: v, cache: y, sharedRootMetaRef: b, invalidateFolders: x, bumpRetry: S, onNotification: C }) => {
+	let [w, T] = l(null), E = c(null), D = s((e, n, i) => {
+		let a = r(i, g);
+		T({
+			files: [{
+				id: `${Date.now()}-archive`,
+				name: n,
+				status: o.Uploading
+			}],
+			isOpen: !0
+		}), (async () => {
+			try {
+				let { results: r } = await f.uploadArchive(e, p, h(a, n)), i = r.filter((e) => e.success).length, o = r.filter((e) => !e.success), s = o.length, { names: c, restCount: l } = m(o);
+				r.length > 0 && i === 0 ? C?.({
+					variant: u.Error,
+					reason: t.UploadArchiveFailed,
+					names: c,
+					restCount: l
+				}) : s > 0 && C?.({
+					variant: u.Error,
+					reason: t.UploadArchivePartiallyFailed,
+					count: s,
+					names: c,
+					restCount: l
+				});
+			} catch {
+				C?.({
+					variant: u.Error,
+					reason: t.UploadArchiveRequestFailed
+				});
+			} finally {
+				x([a]), S(), T(null);
+			}
+		})();
+	}, [
+		p,
+		g,
+		C,
+		f,
+		x,
+		S
+	]);
+	return {
+		onUploadFiles: s((a, s) => {
+			if (a.length === 0) return;
+			let c = _(a);
+			if (c != null) {
+				D(c.fileContent, c.name, s);
+				return;
+			}
+			let l = new AbortController();
+			E.current = l, T({
+				files: a.map((e, t) => ({
+					id: `${Date.now()}-${t}`,
+					name: e.name,
+					status: o.Queued
+				})),
+				isOpen: !0
+			});
+			let m = r(s, g), { bucket: h, path: w } = v === d.Shared ? n(m, b.current, p) : {
+				bucket: p,
+				path: m
+			}, O = new Set((y.get(m) ?? []).map((e) => e.name.toLowerCase()));
+			(async () => {
+				let n = 0, r = 0, s = 0, c = async () => {
+					for (; n < a.length;) {
+						let t = n++, c = a[t];
+						if (l.signal.aborted) {
+							T((e) => i(e, t, o.Cancelled));
+							continue;
+						}
+						T((e) => i(e, t, {
+							status: o.Uploading,
+							percent: 0
+						}));
+						let u = O.has(c.name.toLowerCase()) ? e.Overwrite : e.CreateOnly;
+						try {
+							await f.uploadFile(h, `${w}${c.name}`, c.fileContent, {
+								signal: l.signal,
+								uploadMode: u,
+								onProgress: (e) => {
+									T((n) => i(n, t, {
+										status: o.Uploading,
+										percent: e
+									}));
+								}
+							}), T((e) => i(e, t, {
+								status: o.Completed,
+								percent: 100
+							})), r += 1;
+						} catch {
+							let e = l.signal.aborted ? o.Cancelled : o.Failed;
+							e === o.Failed && (s += 1), T((n) => i(n, t, e));
+						}
+					}
+				};
+				await Promise.all(Array.from({ length: 3 }, () => c())), l.signal.aborted || (r === 0 && s > 0 ? C?.({
+					variant: u.Error,
+					reason: t.UploadFailed
+				}) : C?.({
+					variant: u.Success,
+					reason: t.UploadCompleted,
+					folder: w || g
+				})), x([m]), S(), E.current = null, T(null);
+			})();
+		}, [
+			v,
+			p,
+			y,
+			g,
+			C,
+			f,
+			b,
+			x,
+			S,
+			D
+		]),
+		onUploadArchive: s((e, t, n) => {
+			D(e, t, n);
+		}, [D]),
+		onValidateUpload: s(async (e, t, n) => {
+			for (let t of e) t.name = a(t.name);
+			return { valid: !0 };
+		}, []),
+		uploadBatchState: w,
+		cancelUpload: s(() => {
+			E.current?.abort();
+		}, []),
+		clearUploadBatch: s(() => {
+			T(null);
+		}, [])
+	};
+};
+//#endregion
+export { v as useDialFileUploadBatch };

package/index.d.ts

@@ -135,6 +135,7 @@ import { ToolMenuItem } from '@epam/ai-dial-chat-shared';
 import { ToolsetLoginBodyDto } from '@epam/ai-dial-chat-api-client';
 import { ToolsetLogoutBodyDto } from '@epam/ai-dial-chat-api-client';
 import { ToolsetsApi } from '@epam/ai-dial-chat-api-client';
+import { TranscriptionApi } from '@epam/ai-dial-chat-api-client';
 import { UnpublishCatalogEntityDto } from '@epam/ai-dial-chat-api-client';
 import { UnpublishResultDto } from '@epam/ai-dial-chat-api-client';
 import { UpdateScheduledTaskBodyDto } from '@epam/ai-dial-chat-api-client';
@@ -324,6 +325,26 @@ export declare enum AttachmentValidationErrorReason {
     UnsupportedType = "unsupportedType"
 }
 
+/** Thrown by `transcribeAudio`; carries a machine-readable `reason` instead of translated text. */
+export declare class AudioTranscriptionError extends Error {
+    readonly reason: AudioTranscriptionErrorReason;
+    /** The size limit that was exceeded, present only when `reason` is `TooLarge`. */
+    readonly limitBytes?: number;
+    constructor(reason: AudioTranscriptionErrorReason, limitBytes?: number);
+}
+
+/** Reason a {@link useTranscribeAudio} call failed, translation-free — the host maps it to text. */
+export declare enum AudioTranscriptionErrorReason {
+    /** No usable ASR model or deployment is configured for the current bucket. */
+    Unavailable = "unavailable",
+    /** The recording exceeds the caller's configured size limit. */
+    TooLarge = "tooLarge",
+    /** The upstream ASR provider stayed rate-limited or unavailable after retrying. */
+    Busy = "busy",
+    /** Recognition failed for any other reason. */
+    Failed = "failed"
+}
+
 /** Toolset authentication mechanism as reported by DIAL Core. */
 export declare enum AuthenticationType {
     None = "NONE",
@@ -2735,10 +2756,9 @@ export declare type ResolveDownloadUrl = (fileId: string) => string | undefined;
 /**
  * Returns the content type to trust for an external citation source: `contentType`
  * unchanged when it is already an image/audio/PDF/document-renderer marker,
- * otherwise the type implied by `url`'s path extension (`MIMEType.PDF` for
- * `.pdf`, the
- * canonical MIME for `.docx`/`.xlsx`/`.pptx`/`.csv`) when that extension is
- * recognized, otherwise `contentType` unchanged.
+ * otherwise the type implied by `url`'s path extension (`application/pdf` for
+ * `.pdf`, the canonical MIME for `.docx`/`.xlsx`/`.pptx`/`.csv`) when that
+ * extension is recognized, otherwise `contentType` unchanged.
  *
  * Web-search grounding APIs label every reference — PDFs and Office documents
  * included — as `text/markdown`, so a mislabeled `contentType` must not win
@@ -3511,6 +3531,14 @@ export declare const toPublishEntityType: (type: CatalogEntityType) => CatalogPu
  */
 export declare const toPublishRuleDto: (rule: PublicationRule) => PublishRuleDto;
 
+/** Request shape the host's selected-deployment recognition call accepts. */
+export declare interface TranscribeWithDeploymentParams {
+    audioUrl: string;
+    mimeType: string;
+    deployment: string;
+    signal: AbortSignal;
+}
+
 export declare const trimFileNameToByteLimit: (name: string, limit?: number) => string;
 
 /** An error thrown to indicate the caller is unauthenticated. */
@@ -5265,6 +5293,43 @@ export declare type UseToolsMenuResult = {
     restoreToolConfiguration: (configurationValue: Record<string, unknown> | undefined) => void;
 };
 
+/**
+ * Uploads a complete voice recording to DIAL Core storage and recognizes it,
+ * preferring the configured ASR model and falling back to the selected
+ * deployment. Retries transient upstream failures. Error text is not this
+ * library's concern — callers translate `AudioTranscriptionErrorReason` at
+ * the call site.
+ */
+export declare const useTranscribeAudio: ({ transcriptionApi, filesApi, transcribeWithDeployment, bucket, asrModelId, selectedDeploymentId, maxSizeBytes, }: UseTranscribeAudioParams) => UseTranscribeAudioResult;
+
+/** Parameters for {@link useTranscribeAudio}. */
+export declare interface UseTranscribeAudioParams {
+    /** Already-configured generated-client instance used for the ASR-model path. */
+    transcriptionApi?: Pick<TranscriptionApi, 'transcribeAudio'>;
+    /** Already-configured generated-client instance used to upload the recording. */
+    filesApi: Pick<FilesApi, 'uploadFile'>;
+    /**
+     * Host-configured call for the selected-deployment path. The generated
+     * chat-completions client cannot express this endpoint's `custom_content`
+     * request shape, so the host supplies its own raw request.
+     */
+    transcribeWithDeployment?: (params: TranscribeWithDeploymentParams) => Promise<string>;
+    /** DIAL Core bucket the recording is uploaded into. */
+    bucket: string | undefined | null;
+    /** Recognizes via `transcriptionApi` when set; otherwise `selectedDeploymentId` is used. */
+    asrModelId?: string;
+    /** Deployment id used for recognition when `asrModelId` is not set. */
+    selectedDeploymentId?: string | null;
+    /** Recordings larger than this are rejected with `TooLarge` before upload. */
+    maxSizeBytes: number;
+}
+
+/** Return value of {@link useTranscribeAudio}. */
+export declare interface UseTranscribeAudioResult {
+    /** Uploads and recognizes one complete recording; rejects with an {@link AudioTranscriptionError}. */
+    transcribeAudio: (file: File, signal: AbortSignal) => Promise<string>;
+}
+
 /**
  * Fetches usage stats via the provided `getUserUsage` function on mount.
  *