@acarmisc/backstage-plugin-litellm 0.28.0 → 0.29.0

package/dist/components/ui/tokens.d.ts

@@ -0,0 +1,52 @@
+import type { Theme } from '@mui/material/styles';
+/** `2026-08-16` → `Aug 16`. Falls back to the raw value for anything else. */
+export declare const fmtDateShort: (value: string) => string;
+/** 54253484 → `54.3M`. Keeps axis labels from swallowing the plot area. */
+export declare const fmtCompact: (n: number) => string;
+/** Compact currency for axis ticks — `$24`, `$1.2K`. */
+export declare const fmtUsdCompact: (n: number) => string;
+/** Categorical ramp, ordered so neighbouring series stay distinguishable. */
+export declare const CHART_COLORS: readonly ["#6366F1", "#14B8A6", "#F59E0B", "#EC4899", "#38BDF8", "#84CC16", "#F97316", "#A855F7"];
+/** Fixed colours for series that carry meaning rather than identity. */
+export declare const SERIES: {
+    readonly input: "#6366F1";
+    readonly output: "#14B8A6";
+    readonly success: "#0d9488";
+    readonly failure: "#ea580c";
+    readonly spend: "#F59E0B";
+    readonly budget: "#ea580c";
+};
+/** Stable colour per series name, so a model keeps its colour across charts. */
+export declare function chartColor(name: string): string;
+/** Axis / grid / legend props shared by every chart, derived from the theme. */
+export declare function useChartTheme(): {
+    grid: {
+        stroke: string;
+        strokeDasharray: string;
+        vertical: boolean;
+    };
+    axis: {
+        tick: {
+            fontSize: number;
+            fill: string;
+        };
+        tickLine: boolean;
+        axisLine: {
+            stroke: string;
+        };
+    };
+    legend: {
+        wrapperStyle: {
+            fontSize: number;
+            color: string;
+            paddingTop: number;
+        };
+        iconType: "circle";
+        iconSize: number;
+    };
+    cursor: {
+        fill: string;
+    };
+};
+export type Tone = 'neutral' | 'success' | 'warning' | 'danger' | 'info' | 'accent';
+export declare function toneColor(theme: Theme, tone: Tone): string;

package/dist/ctas.d.ts

@@ -0,0 +1,28 @@
+/** Preset action-bar buttons. `label` overrides the default copy. */
+export type BudgetCtaKind = 'new-key' | 'module' | 'all-limits';
+export interface BudgetCtaSpec {
+    kind: BudgetCtaKind;
+    /** Override the default label. */
+    label?: string;
+}
+/** Either a bare kind (`'module'`) or a spec object (`{ kind: 'module' }`). */
+export type BudgetCta = BudgetCtaKind | BudgetCtaSpec;
+export declare const DEFAULT_CTAS: BudgetCtaKind[];
+/**
+ * Resolves which action-bar buttons to render.
+ *
+ * - `new-key` is shown when explicitly listed, or automatically (first) when
+ *   the user has no keys yet — but never while loading or when the profile
+ *   errored / the user isn't provisioned (a generate flow would fail).
+ * - `all-limits` is dropped when there are no limits to expand.
+ */
+export declare function resolveCtas(spec: {
+    ctas?: BudgetCta[];
+    hasKeys: boolean;
+    viewState: {
+        kind: string;
+    };
+    limitCount: number;
+}): Array<BudgetCtaSpec & {
+    kind: BudgetCtaKind;
+}>;

package/dist/dates.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Convert a Date to a local calendar day string in YYYY-MM-DD format.
+ * Uses local calendar components (getFullYear, getMonth, getDate),
+ * not UTC, to avoid timezone shifts at month/year boundaries.
+ */
+export declare function toLocalDay(d: Date): string;
+/**
+ * Month-to-date range as YYYY-MM-DD strings: the 1st of the current month through today.
+ * Uses local calendar, not UTC, to respect the user's timezone.
+ */
+export declare function monthToDateRange(now?: Date): {
+    startDate: string;
+    endDate: string;
+};
+export type DatePreset = 'today' | '24h' | '7d' | '30d';
+/**
+ * Build a date range from a preset name. Returns an object with
+ * Date objects and pre-formatted YYYY-MM-DD strings for API calls.
+ */
+export declare function localDateRange(preset: DatePreset, now?: Date): {
+    start: Date;
+    end: Date;
+    startDate: string;
+    endDate: string;
+};

package/dist/feedback.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Feedback message generation for toast notifications.
+ * Maps action outcomes to appropriate toast messages and severity levels.
+ */
+export type AlertSeverity = 'success' | 'warning' | 'error' | 'info';
+export interface AlertMessage {
+    message: string;
+    severity: AlertSeverity;
+}
+type ActionKind = 'generateSuccess' | 'generateError' | 'updateSuccess' | 'updateError' | 'blockSuccess' | 'blockError' | 'unblockSuccess' | 'unblockError' | 'resetSpendSuccess' | 'resetSpendError' | 'deleteSuccess' | 'deleteError' | 'deleteAlreadyDeleted' | 'pruneSuccess' | 'prunePartial' | 'pruneError' | 'teamSaveSuccess' | 'teamSaveError' | 'knowledgeBaseSuccess' | 'mcpServerSuccess';
+/**
+ * Generate a toast alert message for an action outcome.
+ * For inline dialog errors (e.g., key form validation), return null
+ * to let the dialog handle it internally.
+ */
+export declare function toastFor(kind: ActionKind, errorMsg?: string): AlertMessage | null;
+export {};

package/dist/format.d.ts

@@ -1,7 +1,43 @@
-export declare const fmtUsd: (n: number) => string;
+/**
+ * Format a number as USD currency with 2 decimals. Non-zero values below
+ * one cent render as `<$0.01`. Zero, null, undefined, or NaN render as `$0.00`.
+ * Negative values keep the leading minus sign.
+ */
+export declare const fmtUsd: (n: number | null | undefined) => string;
 export declare const fmtInt: (n: number) => string;
+/**
+ * Format a count for display, showing "–" when the value is null or undefined.
+ * Used to indicate that data failed to load, distinct from a zero count.
+ */
+export declare const formatCount: (n: number | null | undefined) => string;
 /**
  * Estimate how many tokens a USD budget buys at a given per-token price.
  * Returns null when the price is missing or non-positive.
  */
 export declare const estimateTokensFromBudget: (budget: number, pricePerToken?: number) => number | null;
+/**
+ * Format TPM and RPM limits for display. When neither limit is set (both null/undefined),
+ * returns 'Unlimited'. Otherwise returns formatted values with 'Unlimited' for the missing limit.
+ * Uses fmtInt for digit grouping.
+ */
+export declare const fmtLimits: (tpm: number | null | undefined, rpm: number | null | undefined) => string;
+export interface ModelInfo {
+    model_name: string;
+}
+export interface UsageModelBreakdown {
+    total_spend: number;
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    api_requests: number;
+    successful_requests: number;
+    failed_requests: number;
+}
+/**
+ * Filter models to only those that have usage data in the given period.
+ * Keeps 'all' as a first option and extracts model names from the full list,
+ * then filters to only those present in the usage breakdown.
+ */
+export declare const modelsWithUsage: (usage: {
+    usage_by_model?: Record<string, UsageModelBreakdown>;
+} | null, models: ModelInfo[]) => string[];

package/dist/homeWidgetHelpers.d.ts

@@ -0,0 +1,40 @@
+import type { UsageMetrics } from './types';
+/**
+ * Build a human-readable date range caption from two YYYY-MM-DD strings.
+ * Example: '2026-09-01', '2026-09-29' → 'Sep 1 – Sep 29'
+ */
+export declare function rangeCaption(startDay: string, endDay: string): string;
+/**
+ * Build a month-to-date range caption from a Date.
+ * Example: new Date('2026-09-29') → 'Sep 1 – 29'
+ * Handles same-day (returns date twice) and month/year edge cases.
+ */
+export declare function mtdCaption(now?: Date): string;
+/**
+ * Build an aria-label summary for a sparkline chart showing daily spend data.
+ * Includes total spend, peak value, and the date it occurred.
+ * Example: 'Daily spend over 7 days, total $129.90, peak $41.20 on Sep 27'
+ */
+export declare function sparklineAriaLabel(points: Array<{
+    date: string;
+    spend: number;
+}>): string;
+/**
+ * Format usage metrics as a single summary line: '$X spent · YM in · ZM out'
+ * Handles zero usage and undefined values gracefully.
+ */
+export declare function usageSummary(usage: UsageMetrics | null | undefined): string;
+/**
+ * Build ARIA attributes for a meter component showing a percentage value.
+ * When value > 100%, sets aria-valuetext to include "over cap" warning.
+ * Returns an object with role, aria-valuenow, aria-valuemin, aria-valuemax,
+ * aria-label, and optionally aria-valuetext.
+ */
+export declare function meterAria(pct: number, label?: string): {
+    role: string;
+    'aria-valuenow': number;
+    'aria-valuemin': number;
+    'aria-valuemax': number;
+    'aria-label'?: string;
+    'aria-valuetext'?: string;
+};

package/dist/hooks/index.d.ts

@@ -0,0 +1,3 @@
+export { useCopyToClipboard } from './useCopyToClipboard';
+export { useLiteLLMProfile, invalidateLiteLLMProfile } from './useLiteLLMProfile';
+export type { LiteLLMProfileResult } from './useLiteLLMProfile';

package/dist/hooks/useCopyToClipboard.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Pure helper: determine if the Clipboard API is available.
+ */
+export declare function isClipboardApiAvailable(): boolean;
+/**
+ * Pure helper: fallback copy via textarea and document.execCommand.
+ * Returns true if successful, false otherwise.
+ */
+export declare function fallbackCopyToClipboard(text: string): boolean;
+/**
+ * Pure helper: create a timer for the copied state.
+ * Returns the timer ID so the caller can manage cleanup.
+ */
+export declare function startCopiedTimer(onCopiedChange: (copied: boolean) => void, durationMs?: number): ReturnType<typeof setTimeout>;
+/**
+ * Hook: copy text to clipboard with visual feedback.
+ *
+ * @returns {copy, copied, error} - async copy function, copied state, and error if any
+ *
+ * - `copy(text)`: async function that copies text and returns true if successful
+ * - `copied`: true for 2s after successful copy, then resets
+ * - `error`: error object if copy failed; shows via alertApi
+ *
+ * Uses navigator.clipboard.writeText with fallback to textarea + execCommand.
+ */
+export declare function useCopyToClipboard(): {
+    copy: (text: string) => Promise<boolean>;
+    copied: boolean;
+    error: Error | null;
+};

package/dist/hooks/useLiteLLMProfile.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Unified hook for fetching the user's LiteLLM profile: userInfo, teams, keys, models, and config.
+ * Results are cached per API instance with a 30s TTL and single-flight deduplication.
+ * Callers can invalidate the cache after mutations to ensure fresh data.
+ */
+import { LiteLlmApiInterface } from '../api';
+import { UserInfo, TeamInfo, VirtualKey, ModelInfo, LiteLlmConfig } from '../types';
+import { ProfileCache } from '../profileCache';
+export interface LiteLLMProfileResult {
+    userInfo: UserInfo | null;
+    teams: TeamInfo[];
+    keys: VirtualKey[];
+    models: ModelInfo[];
+    config: LiteLlmConfig | null;
+    loading: boolean;
+    error: string | null;
+    retry: () => void;
+}
+/**
+ * Fetch the complete user profile (userInfo, teams, keys, models, config).
+ * Results are cached with a 30s TTL and single-flight deduplication per API instance.
+ * Call the returned `retry()` after mutations to invalidate the cache.
+ */
+export declare function useLiteLLMProfile(cache?: ProfileCache): LiteLLMProfileResult;
+/**
+ * Invalidate the profile cache for an API instance after a mutation
+ * (e.g., after creating/updating/deleting a key or team).
+ *
+ * @param api The API instance to invalidate.
+ * @param cache The cache instance (defaults to the singleton).
+ */
+export declare function invalidateLiteLLMProfile(api: LiteLlmApiInterface, cache?: ProfileCache): void;