@epam/ai-dial-chat-hooks 1.2.0-dev.14 → 1.2.0-dev.142

package/usage/map-usage-data-to-dashboard.js

@@ -0,0 +1,66 @@
+import { formatCost as e } from "@epam/ai-dial-chat-shared";
+import { UsageLimitStatus as t } from "@epam/ai-dial-usage-dashboard";
+//#region src/usage/map-usage-data-to-dashboard.ts
+var n = {
+	todayTitle: "usage.todayTitle",
+	todayPeriodDescription: "usage.todayPeriodDescription",
+	thisWeekTitle: "usage.thisWeekTitle",
+	thisWeekPeriodDescription: "usage.thisWeekPeriodDescription",
+	thisMonthTitle: "usage.thisMonthTitle",
+	thisMonthPeriodDescription: "usage.thisMonthPeriodDescription",
+	unlimitedProgressAriaLabel: "usage.unlimitedProgressAriaLabel",
+	progressAriaLabel: "usage.progressAriaLabel"
+}, r = 2 ** 53, i = 75, a = (e) => e != null && Number.isFinite(e.total) && Number.isFinite(e.used), o = (e) => e >= 100 ? t.LimitReached : e >= i ? t.RunningLow : t.Default, s = (e) => e ? {
+	resetLabel: e.label,
+	resetIsoValue: e.isoValue,
+	resetAriaLabel: e.ariaLabel
+} : {}, c = (i, a, c, l, u) => {
+	let d = Math.max(0, i.used), f = e(d), p = s(u);
+	if (i.total >= r) return {
+		title: a,
+		periodDescription: c,
+		used: d,
+		total: i.total,
+		usedLabel: f,
+		isUnlimited: !0,
+		status: t.Default,
+		progressAriaLabel: l(n.unlimitedProgressAriaLabel, { used: f }),
+		...p
+	};
+	let m = Math.max(i.total, 0), h = Math.max(m - d, 0), g = m > 0 ? d / m * 100 : 100, _ = e(m);
+	return {
+		title: a,
+		periodDescription: c,
+		used: d,
+		total: m,
+		usedLabel: f,
+		totalLabel: _,
+		remainingLabel: e(h),
+		usedPercent: g,
+		status: o(g),
+		progressAriaLabel: l(n.progressAriaLabel, {
+			used: f,
+			total: _,
+			percent: Math.round(g)
+		}),
+		...p
+	};
+}, l = (e, t, r) => [
+	{
+		stats: e?.dayCostStats,
+		titleKey: n.todayTitle,
+		periodDescriptionKey: n.todayPeriodDescription
+	},
+	{
+		stats: e?.weekCostStats,
+		titleKey: n.thisWeekTitle,
+		periodDescriptionKey: n.thisWeekPeriodDescription
+	},
+	{
+		stats: e?.monthCostStats,
+		titleKey: n.thisMonthTitle,
+		periodDescriptionKey: n.thisMonthPeriodDescription
+	}
+].flatMap(({ stats: e, titleKey: n, periodDescriptionKey: i }) => a(e) ? [c(e, t(n), t(i), t, r(e.resetsAt))] : []);
+//#endregion
+export { n as USAGE_DATA_I18N_KEYS, l as mapUsageDataToDashboard };

package/usage/map-user-usage-to-model-limits.js

@@ -0,0 +1,160 @@
+import { formatCost as e } from "@epam/ai-dial-chat-shared";
+import { DeploymentItemDtoTypeEnum as t } from "@epam/ai-dial-chat-api-client";
+import { ModelLimitMetricKind as n, ModelLimitStatus as r } from "@epam/ai-dial-usage-dashboard";
+//#region src/usage/map-user-usage-to-model-limits.ts
+var i = 2 ** 53, a = 75, o = new Intl.NumberFormat(void 0, {
+	notation: "compact",
+	maximumFractionDigits: 1
+}), s = new Intl.NumberFormat(void 0, { maximumFractionDigits: 2 }), c = {
+	todayPeriodDescription: "usage.todayPeriodDescription",
+	thisWeekPeriodDescription: "usage.thisWeekPeriodDescription",
+	thisMonthPeriodDescription: "usage.thisMonthPeriodDescription",
+	overallCostLimitRunningLowTooltip: "usage.overallCostLimitRunningLowTooltip",
+	overallCostLimitReachedTooltip: "usage.overallCostLimitReachedTooltip",
+	unavailableLabel: "usage.unavailableLabel",
+	followsCostLimitLabel: "usage.followsCostLimitLabel",
+	noLimitLabel: "usage.noLimitLabel",
+	followsCostLimitAriaLabel: "usage.followsCostLimitAriaLabel",
+	unlimitedProgressAriaLabel: "usage.unlimitedProgressAriaLabel",
+	progressAriaLabel: "usage.progressAriaLabel",
+	spentLabel: "usage.spentLabel"
+}, l = {
+	day: {
+		cost: "dayCostStats",
+		tokens: "dayTokenStats"
+	},
+	week: {
+		cost: "weekCostStats",
+		tokens: "weekTokenStats"
+	},
+	month: {
+		cost: "monthCostStats",
+		tokens: "monthTokenStats"
+	}
+}, u = {
+	day: {
+		field: "dayCostStats",
+		labelKey: c.todayPeriodDescription
+	},
+	week: {
+		field: "weekCostStats",
+		labelKey: c.thisWeekPeriodDescription
+	},
+	month: {
+		field: "monthCostStats",
+		labelKey: c.thisMonthPeriodDescription
+	}
+}, d = (e) => e != null && Number.isFinite(e.total) && Number.isFinite(e.used), f = (e) => e >= 100 ? r.LimitReached : e >= a ? r.RunningLow : r.WithinLimits, p = (e) => {
+	if (!d(e)) return r.Unavailable;
+	if (e.total >= i) return r.NoLimit;
+	let t = Math.max(0, e.used), n = Math.max(0, e.total);
+	return f(n > 0 ? t / n * 100 : 100);
+}, m = (e) => e === r.WithinLimits || e === r.RunningLow || e === r.LimitReached, h = (e, t, n, i, a) => {
+	let o = e?.[t.field], s = p(o), l = a(o?.resetsAt), u = i(t.labelKey).toLocaleLowerCase(n);
+	return {
+		status: s,
+		tooltipLabel: s === r.LimitReached ? i(c.overallCostLimitReachedTooltip, { period: u }) : s === r.RunningLow ? i(c.overallCostLimitRunningLowTooltip, { period: u }) : void 0,
+		...l ? {
+			resetLabel: l.label,
+			resetIsoValue: l.isoValue,
+			resetAriaLabel: l.ariaLabel
+		} : {}
+	};
+}, g = () => void 0, _ = (e, t, n, r = g) => ({
+	day: h(e, u.day, t, n, r),
+	week: h(e, u.week, t, n, r),
+	month: h(e, u.month, t, n, r)
+}), v = (e) => ({
+	kind: n.Unavailable,
+	ariaLabel: e(c.unavailableLabel)
+}), y = (e, t, r) => {
+	if (!d(e)) return v(r);
+	let a = Math.max(0, e.used), l = o.format(a);
+	if (e.total >= i) {
+		let e = m(t);
+		return {
+			kind: n.Unlimited,
+			usedLabel: l,
+			supportingLabel: r(e ? c.followsCostLimitLabel : c.noLimitLabel),
+			ariaLabel: r(e ? c.followsCostLimitAriaLabel : c.unlimitedProgressAriaLabel, { used: s.format(a) })
+		};
+	}
+	let u = Math.max(e.total, 0), p = o.format(u), h = u > 0 ? a / u * 100 : 100, g = f(h);
+	return {
+		kind: n.Finite,
+		usedLabel: l,
+		totalLabel: p,
+		usedPercent: h,
+		status: g,
+		ariaLabel: r(c.progressAriaLabel, {
+			used: s.format(a),
+			total: s.format(u),
+			percent: Math.round(h)
+		})
+	};
+}, b = (t, r) => {
+	if (!d(t)) return v(r);
+	let a = Math.max(0, t.used), o = r(c.spentLabel, { amount: e(a) });
+	if (t.total >= i) return {
+		kind: n.Unlimited,
+		usedLabel: o,
+		ariaLabel: o
+	};
+	let s = Math.max(t.total, 0), l = s > 0 ? a / s * 100 : 100;
+	return {
+		kind: n.Finite,
+		usedLabel: o,
+		totalLabel: e(s),
+		usedPercent: l,
+		status: f(l),
+		ariaLabel: r(c.progressAriaLabel, {
+			used: e(a),
+			total: e(s),
+			percent: Math.round(l)
+		})
+	};
+}, x = (e, t, n, r) => ({
+	tokens: y(e[t.tokens], n, r),
+	cost: b(e[t.cost], r)
+}), S = (e) => e.filter((e) => e.kind === n.Finite).map((e) => e.status), C = (e, t, i) => {
+	let a = [
+		...S(e),
+		...S(t),
+		...i
+	].filter((e) => e != null && m(e));
+	return a.includes(r.LimitReached) ? r.LimitReached : a.includes(r.RunningLow) ? r.RunningLow : a.includes(r.WithinLimits) ? r.WithinLimits : e.some((e) => e.kind === n.Unlimited) || i.includes(r.NoLimit) ? r.NoLimit : r.Unavailable;
+}, w = (e) => e.some((e) => d(e) && e.used > 0), T = (e, n, r, i, a, o) => {
+	let s = e?.deployments;
+	if (s == null) return [];
+	let c = new Map(n.filter((e) => e.type === t.Model).map((e) => [e.id, e])), u = _(e, r, i);
+	return Object.keys(s).map((e) => {
+		let t = c.get(e), n = t == null ? e : o(t.displayName, r) || t.id, d = s[e], f = a(t?.iconUrl), p = x(d, l.day, u.day.status, i), m = x(d, l.week, u.week.status, i), h = x(d, l.month, u.month.status, i), g = Object.values(l).flatMap(({ cost: e, tokens: t }) => [d[e], d[t]]);
+		return {
+			row: {
+				id: e,
+				name: n,
+				version: t?.displayVersion,
+				avatarSrc: f,
+				day: p,
+				week: m,
+				month: h,
+				status: C([
+					p.tokens,
+					m.tokens,
+					h.tokens
+				], [
+					p.cost,
+					m.cost,
+					h.cost
+				], [
+					u.day.status,
+					u.week.status,
+					u.month.status
+				])
+			},
+			hasUsage: w(g)
+		};
+	}).filter(({ hasUsage: e }) => e).map(({ row: e }) => e);
+};
+//#endregion
+export { c as USAGE_MODEL_LIMITS_I18N_KEYS, _ as mapOverallCostLimitsToPeriodStatuses, T as mapUserUsageToModelLimits };

package/usage.d.ts

@@ -0,0 +1,120 @@
+import { DeploymentItemDto } from '@epam/ai-dial-chat-api-client';
+import { ModelLimitPeriodStatuses } from '@epam/ai-dial-usage-dashboard';
+import { ModelLimitRow } from '@epam/ai-dial-usage-dashboard';
+import { UsageLimitCardData } from '@epam/ai-dial-usage-dashboard';
+import { UserLimitStatsResponseDto } from '@epam/ai-dial-chat-api-client';
+
+/** Formats a raw `resetsAt` into display strings, or returns `undefined` when it cannot be formatted. */
+export declare type FormatResetTime = (resetsAt: string | undefined) => ResetTimeDisplay | undefined;
+
+/**
+ * Maps the same top-level Cost budgets used by the aggregate cards into table-header state.
+ *
+ * @param formatResetTime - Formats each period's top-level `resetsAt` into the header's reset trio. Omit it to produce statuses with no reset fields.
+ */
+export declare const mapOverallCostLimitsToPeriodStatuses: (usage: UserLimitStatsResponseDto | undefined, activeLocale: string, t: Translate_2, formatResetTime?: FormatResetTime) => ModelLimitPeriodStatuses;
+
+/**
+ * Maps a `UserLimitStatsResponseDto` into `UsageLimitCardGroup`'s `cards` prop,
+ * in Today / This week / This month order. A period is omitted entirely when
+ * the response carries no usable stat for it. Each card's reset trio comes from
+ * `formatResetTime`, and is absent when that callback returns `undefined`.
+ */
+export declare const mapUsageDataToDashboard: (usage: UserLimitStatsResponseDto | undefined, t: Translate, formatResetTime: FormatResetTime) => UsageLimitCardData[];
+
+/**
+ * Maps `usage.deployments` into `ModelLimitsSection`'s `rows` prop, joined with model identity
+ * from `deploymentItems`. Rows are included only when any displayed period stat has nonzero usage.
+ * Order follows `Object.keys(deployments)` — `deploymentItems` is enrichment-only.
+ *
+ * @param resolveIconUrl - Resolves a deployment's raw `iconUrl` to the URL the avatar should load.
+ * @param resolveDisplayName - Resolves a localized-text map or plain string to the display name for `activeLocale`.
+ */
+export declare const mapUserUsageToModelLimits: (usage: UserLimitStatsResponseDto | undefined, deploymentItems: DeploymentItemDto[], activeLocale: string, t: Translate_2, resolveIconUrl: ResolveIconUrl, resolveDisplayName: ResolveDisplayName) => ModelLimitRow[];
+
+/**
+ * One reset time, already parsed and formatted by the host. Declared
+ * structurally here so this library never imports an application type; the
+ * host passes a value that satisfies this shape (e.g. `apps/chat`'s own
+ * `ResetTimeDisplay`).
+ */
+export declare interface ResetTimeDisplay {
+    /** Exclusive end of the period as an epoch ms value, for the host's boundary scheduling. */
+    resetsAtMs: number;
+    /** Machine-readable instant for a `<time dateTime>` attribute. */
+    isoValue: string;
+    /** Visible reset line. */
+    label: string;
+    /** Accessible expansion of the reset line. */
+    ariaLabel: string;
+}
+
+/** A callback that resolves a display name from a localized-text value. */
+declare type ResolveDisplayName = (name: string | Record<string, string> | undefined | null, locale: string) => string;
+
+/** A callback that resolves an icon URL from a deployment's raw `iconUrl` field. */
+declare type ResolveIconUrl = (iconUrl: string | undefined) => string | undefined;
+
+/** A translate function compatible with i18next's `TFunction`. */
+declare type Translate = (key: string, options?: Record<string, unknown>) => string;
+
+/** A translate function compatible with i18next's `TFunction`. */
+declare type Translate_2 = (key: string, options?: Record<string, unknown>) => string;
+
+/**
+ * i18n key strings that the consuming app's translation bundle must define for
+ * `mapUsageDataToDashboard` to produce correctly translated strings. The
+ * values are the default key paths used by AI DIAL Chat.
+ */
+export declare const USAGE_DATA_I18N_KEYS: {
+    /** Title for the current-UTC-day card (e.g. `'Today'`). */
+    readonly todayTitle: "usage.todayTitle";
+    /** Accessible period description for the current-UTC-day card. */
+    readonly todayPeriodDescription: "usage.todayPeriodDescription";
+    /** Title for the current-UTC-week card (e.g. `'This week'`). */
+    readonly thisWeekTitle: "usage.thisWeekTitle";
+    /** Accessible period description for the current-UTC-week card. */
+    readonly thisWeekPeriodDescription: "usage.thisWeekPeriodDescription";
+    /** Title for the current-UTC-month card (e.g. `'This month'`). */
+    readonly thisMonthTitle: "usage.thisMonthTitle";
+    /** Accessible period description for the current-UTC-month card. */
+    readonly thisMonthPeriodDescription: "usage.thisMonthPeriodDescription";
+    /** Aria label when there is no limit. Receives `{ used: string }`. */
+    readonly unlimitedProgressAriaLabel: "usage.unlimitedProgressAriaLabel";
+    /** Aria label for a progress bar with a finite limit. Receives `{ used: string, total: string, percent: number }`. */
+    readonly progressAriaLabel: "usage.progressAriaLabel";
+};
+
+/**
+ * i18n key strings that the consuming app's translation bundle must define for
+ * `mapUserUsageToModelLimits` and `mapOverallCostLimitsToPeriodStatuses` to produce
+ * correctly translated strings. The values are the default key paths used by AI DIAL Chat.
+ */
+export declare const USAGE_MODEL_LIMITS_I18N_KEYS: {
+    /** Period label used in tooltip text. Receives no interpolation. */
+    readonly todayPeriodDescription: "usage.todayPeriodDescription";
+    /** Period label used in tooltip text. Receives no interpolation. */
+    readonly thisWeekPeriodDescription: "usage.thisWeekPeriodDescription";
+    /** Period label used in tooltip text. Receives no interpolation. */
+    readonly thisMonthPeriodDescription: "usage.thisMonthPeriodDescription";
+    /** Tooltip when the overall cost limit is running low. Receives `{ period: string }`. */
+    readonly overallCostLimitRunningLowTooltip: "usage.overallCostLimitRunningLowTooltip";
+    /** Tooltip when the overall cost limit is reached. Receives `{ period: string }`. */
+    readonly overallCostLimitReachedTooltip: "usage.overallCostLimitReachedTooltip";
+    /** Aria label for a metric cell with no data. */
+    readonly unavailableLabel: "usage.unavailableLabel";
+    /** Supporting label when a token limit follows the cost limit. */
+    readonly followsCostLimitLabel: "usage.followsCostLimitLabel";
+    /** Supporting label when there is no per-deployment token limit. */
+    readonly noLimitLabel: "usage.noLimitLabel";
+    /** Aria label when token usage has no limit but follows the cost limit. Receives `{ used: string }`. */
+    readonly followsCostLimitAriaLabel: "usage.followsCostLimitAriaLabel";
+    /** Aria label when there is no limit. Receives `{ used: string }`. */
+    readonly unlimitedProgressAriaLabel: "usage.unlimitedProgressAriaLabel";
+    /** Aria label for a progress bar with a finite limit. Receives `{ used: string, total: string, percent: number }`. */
+    readonly progressAriaLabel: "usage.progressAriaLabel";
+    /** Label for the spent-cost cell. Receives `{ amount: string }`. */
+    readonly spentLabel: "usage.spentLabel";
+};
+
+export { }

package/usage.js

@@ -0,0 +1,3 @@
+import { USAGE_DATA_I18N_KEYS as e, mapUsageDataToDashboard as t } from "./usage/map-usage-data-to-dashboard.js";
+import { USAGE_MODEL_LIMITS_I18N_KEYS as n, mapOverallCostLimitsToPeriodStatuses as r, mapUserUsageToModelLimits as i } from "./usage/map-user-usage-to-model-limits.js";
+export { e as USAGE_DATA_I18N_KEYS, n as USAGE_MODEL_LIMITS_I18N_KEYS, r as mapOverallCostLimitsToPeriodStatuses, t as mapUsageDataToDashboard, i as mapUserUsageToModelLimits };

package/utils.d.ts

@@ -10,6 +10,8 @@ import { UserLimitStatsResponseDto } from '@epam/ai-dial-chat-api-client';
 
 /** Normalized shape returned by {@link getApiErrorDetails}. */
 export declare interface ApiErrorDetails {
+    /** Stable domain error code supplied by the API, when present. */
+    code?: string;
     /** HTTP status code carried by the error, when available. */
     status?: number;
     /** Resolved human-readable error message, or `null` when none could be resolved. */
@@ -132,7 +134,7 @@ export declare interface ExportedPrompt {
 /** Formats a Unix timestamp (ms) as a locale-formatted calendar date, e.g. `'22/7/2026'`. */
 export declare const formatCalendarDate: (timestampMs: number) => string;
 
-/** Normalizes any API error into a `{ status?, message, traceId? }` shape. */
+/** Normalizes any API error into a `{ status?, message, traceId?, code? }` shape. */
 export declare const getApiErrorDetails: (error: unknown) => Promise<ApiErrorDetails>;
 
 /** Resolves a human-readable message from an API error's response body, or falls back to `Error.message`. */