@acarmisc/backstage-plugin-litellm 0.27.0 → 0.29.0

package/dist/keyFilter.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pure filtering functions for key lists.
+ */
+import { VirtualKey } from './types';
+export type KeyFilterType = 'expired' | 'expiring' | undefined;
+/**
+ * Filter keys by expiry status.
+ * @param keys List of keys to filter
+ * @param filter Filter type: 'expired', 'expiring', or undefined (no filter)
+ * @returns Filtered list of keys
+ */
+export declare function filterKeysByStatus(keys: VirtualKey[], filter: KeyFilterType): VirtualKey[];

package/dist/keyFormValidation.d.ts

@@ -0,0 +1,38 @@
+import { GenerateKeyRequest, UpdateKeyRequest } from './types';
+export interface ValidationErrors {
+    alias?: string;
+    team?: string;
+    budget?: string;
+    duration?: string;
+    models?: string;
+}
+export interface ValidationOptions {
+    teamRequired?: boolean;
+    /** True when the user has ticked the 'Unlimited budget' checkbox. */
+    unlimitedBudget?: boolean;
+    isCreate?: boolean;
+}
+/**
+ * Validates a key form (create or edit mode).
+ * Returns a map of field names to error messages.
+ * A field with no error is absent from the map.
+ */
+export declare function validateKeyForm(formData: GenerateKeyRequest | UpdateKeyRequest, options?: ValidationOptions): ValidationErrors;
+/**
+ * Returns the first field with an error, in a consistent order.
+ * Used to focus the first invalid field on submit.
+ */
+export declare function firstInvalidField(errors: ValidationErrors, isCreate?: boolean): string | null;
+/**
+ * Compute the expiry date from a duration string and the current date.
+ * Supported: 'd' (days), 'w' (weeks), 'm' (months), 'y' (years).
+ * Example: expiryPreview('30d', new Date('2026-09-29')) => 'Expires Oct 29, 2026'
+ */
+export declare function expiryPreview(duration: string | undefined, now?: Date): string | null;
+/**
+ * Find the priciest input cost among selected models.
+ * Returns null if no models have pricing data.
+ */
+export declare function priciestInputPrice(selectedModels: Array<{
+    input_cost_per_token?: number;
+}>): number | null;

package/dist/keyLabels.d.ts

@@ -0,0 +1,16 @@
+import type { VirtualKey } from './types';
+/**
+ * Returns a display label for a key: alias if present, otherwise the masked key.
+ * Handles missing alias and odd/short masked strings gracefully.
+ */
+export declare function keyDisplayLabel(key: VirtualKey): string;
+/**
+ * Extracts the last 4 characters from a key's masked value.
+ * Returns empty string if the key is shorter than 4 chars.
+ */
+export declare function keyLast4(key: VirtualKey): string;
+/**
+ * Generates the confirmation copy for pruning expired keys.
+ * Handles singular and plural correctly.
+ */
+export declare function pruneCopy(n: number): string;

package/dist/permissions.d.ts

@@ -1,5 +1 @@
-export declare const litellmTeamCreatePermission: import("@backstage/plugin-permission-common").BasicPermission;
-export declare const litellmTeamManagePermission: import("@backstage/plugin-permission-common").BasicPermission;
-export declare const litellmTeamMembersManagePermission: import("@backstage/plugin-permission-common").BasicPermission;
-export declare const litellmTeamKnowledgebaseManagePermission: import("@backstage/plugin-permission-common").BasicPermission;
-export declare const litellmTeamMcpManagePermission: import("@backstage/plugin-permission-common").BasicPermission;
+export { litellmKeyCreatePermission, litellmKeyRevokePermission, litellmKeyManagePermission, litellmKeyResetSpendPermission, litellmKeyUnblockPermission, litellmAuditReadPermission, litellmTeamCreatePermission, litellmTeamManagePermission, litellmTeamMembersManagePermission, litellmTeamKnowledgebaseManagePermission, litellmTeamMcpManagePermission, litellmTeamDeletePermission, litellmPermissions, } from '@acarmisc/backstage-plugin-litellm-common';

package/dist/plugin.d.ts

@@ -1,5 +1,6 @@
-import React from 'react';
-export declare const litellmPlugin: import("@backstage/frontend-plugin-api").OverridableFrontendPlugin<{}, {}, {
+export declare const litellmPlugin: import("@backstage/frontend-plugin-api").OverridableFrontendPlugin<{
+    root: import("@backstage/frontend-plugin-api").RouteRef<undefined>;
+}, {}, {
     "api:litellm": import("@backstage/frontend-plugin-api").OverridableExtensionDefinition<{
         kind: "api";
         name: undefined;
@@ -22,13 +23,13 @@ export declare const litellmPlugin: import("@backstage/frontend-plugin-api").Ove
         };
         output: import("@backstage/frontend-plugin-api").ExtensionDataRef<string, "core.routing.path", {}> | import("@backstage/frontend-plugin-api").ExtensionDataRef<import("@backstage/frontend-plugin-api").RouteRef<import("@backstage/frontend-plugin-api").AnyRouteRefParams>, "core.routing.ref", {
             optional: true;
-        }> | import("@backstage/frontend-plugin-api").ExtensionDataRef<React.JSX.Element, "core.reactElement", {}> | import("@backstage/frontend-plugin-api").ExtensionDataRef<string, "core.title", {
+        }> | import("@backstage/frontend-plugin-api").ExtensionDataRef<import("react").JSX.Element, "core.reactElement", {}> | import("@backstage/frontend-plugin-api").ExtensionDataRef<string, "core.title", {
             optional: true;
         }> | import("@backstage/frontend-plugin-api").ExtensionDataRef<import("@backstage/frontend-plugin-api").IconElement, "core.icon", {
             optional: true;
         }>;
         inputs: {
-            pages: import("@backstage/frontend-plugin-api").ExtensionInput<import("@backstage/frontend-plugin-api").ConfigurableExtensionDataRef<React.JSX.Element, "core.reactElement", {}> | import("@backstage/frontend-plugin-api").ConfigurableExtensionDataRef<string, "core.routing.path", {}> | import("@backstage/frontend-plugin-api").ConfigurableExtensionDataRef<import("@backstage/frontend-plugin-api").RouteRef<import("@backstage/frontend-plugin-api").AnyRouteRefParams>, "core.routing.ref", {
+            pages: import("@backstage/frontend-plugin-api").ExtensionInput<import("@backstage/frontend-plugin-api").ConfigurableExtensionDataRef<import("react").JSX.Element, "core.reactElement", {}> | import("@backstage/frontend-plugin-api").ConfigurableExtensionDataRef<string, "core.routing.path", {}> | import("@backstage/frontend-plugin-api").ConfigurableExtensionDataRef<import("@backstage/frontend-plugin-api").RouteRef<import("@backstage/frontend-plugin-api").AnyRouteRefParams>, "core.routing.ref", {
                 optional: true;
             }> | import("@backstage/frontend-plugin-api").ConfigurableExtensionDataRef<string, "core.title", {
                 optional: true;
@@ -44,7 +45,7 @@ export declare const litellmPlugin: import("@backstage/frontend-plugin-api").Ove
             path: string;
             title?: string;
             icon?: import("@backstage/frontend-plugin-api").IconElement;
-            loader?: () => Promise<React.JSX.Element>;
+            loader?: () => Promise<import("react").JSX.Element>;
             routeRef?: import("@backstage/frontend-plugin-api").RouteRef;
             noHeader?: boolean;
         };

package/dist/profileCache.d.ts

@@ -0,0 +1,46 @@
+/**
+ * A per-API-instance promise cache with TTL and single-flight deduplication.
+ * Used to memoize the profile hook's result and reduce redundant fetches.
+ *
+ * Each API instance gets its own cache entry; entries expire after a TTL.
+ * Concurrent callers for the same key within the TTL share a single promise
+ * and wait for its result rather than issuing parallel requests.
+ *
+ * Injectable clock for testing.
+ */
+import { LiteLlmApiInterface } from './api';
+export interface Clock {
+    now(): number;
+}
+export declare const systemClock: Clock;
+export interface ProfileCacheEntry {
+    result: unknown;
+    timestamp: number;
+}
+export declare class ProfileCache {
+    private cache;
+    private inflight;
+    private ttlMs;
+    private clock;
+    constructor(ttlMs?: number, clock?: Clock);
+    /**
+     * Fetch or return a cached value. If a concurrent call with the same key
+     * is in-flight, wait for it rather than issuing a parallel request.
+     *
+     * @param api The API instance (cache is scoped to it).
+     * @param key A string key for the result (e.g., 'profile' or a team ID).
+     * @param fetcher A thunk that returns the value to cache.
+     * @returns The cached value (hit or miss) or the result of fetcher().
+     */
+    memoize<T>(api: LiteLlmApiInterface, key: string, fetcher: () => Promise<T>): Promise<T>;
+    /**
+     * Invalidate all cached entries for an API instance, including inflight requests.
+     */
+    invalidate(api: LiteLlmApiInterface): void;
+    /**
+     * Invalidate every profile entry (`profile`, `profile-userInfo`,
+     * `profile-keys`, ...) and its in-flight promise, leaving unrelated keys alone.
+     */
+    invalidateProfile(api: LiteLlmApiInterface): void;
+}
+export declare const profileCacheInstance: ProfileCache;

package/dist/routeHelpers.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Build a link to the keys tab on the LiteLLM page.
+ * @param baseUrl - The base URL of the LiteLLM module (result from useRouteRef)
+ * @returns The full URL to the keys tab, or undefined if baseUrl is not available
+ */
+export declare function buildKeysLink(baseUrl: string | undefined): string | undefined;

package/dist/routes.d.ts

@@ -0,0 +1 @@
+export declare const rootRouteRef: import("@backstage/frontend-plugin-api").RouteRef<undefined>;

package/dist/types.d.ts

@@ -1,48 +1,4 @@
-export interface UserInfo {
-    user_id: string;
-    user_email?: string;
-    email?: string;
-    teams?: string[];
-    models?: string[];
-    max_budget?: number;
-    spend?: number;
-    current_spend?: number;
-    soft_limit?: number;
-    hard_limit?: number;
-    /** Spend-reset period for max_budget, e.g. "30d". */
-    budget_duration?: string;
-    /** Backstage-computed: true when the user belongs to litellm.audit.group */
-    can_view_audit?: boolean;
-}
-export interface TeamMember {
-    user_id: string;
-    user_email?: string;
-    role: 'admin' | 'user';
-}
-export interface TeamObjectPermission {
-    vector_stores?: string[];
-    mcp_servers?: string[];
-    mcp_access_groups?: string[];
-}
-export interface TeamInfo {
-    team_id: string;
-    team_alias?: string;
-    max_budget?: number;
-    budget_duration?: string;
-    spend: number;
-    /** Share of max_budget consumed (0-100), present only on redacted records. */
-    budget_pct?: number;
-    /** ok | near (>=80%) | over (>=100%), present only on redacted records. */
-    budget_status?: 'ok' | 'near' | 'over';
-    /** True when the backend stripped max_budget/spend (budget hiding enabled). */
-    budget_hidden?: boolean;
-    members_with_roles?: TeamMember[];
-    models?: string[];
-    tpm_limit?: number;
-    rpm_limit?: number;
-    metadata?: Record<string, unknown>;
-    object_permission?: TeamObjectPermission;
-}
+export { type UserInfo, type TeamMember, type TeamObjectPermission, type TeamInfo, type VirtualKey, type ModelInfo, type UsageModelBreakdown, type UsageKeyBreakdown, type UsageDailyPoint, type UsageDailyModelPoint, type UsageMetrics, type GenerateKeyRequest, type UpdateKeyRequest, type GenerateKeyResponse, type AuditLogEntry, type PaginatedAuditLogs, type AuditLogsParams, type CreateTeamResponse, } from '@acarmisc/backstage-plugin-litellm-common';
 export interface VectorStoreInfo {
     id: string;
     name?: string;
@@ -52,120 +8,11 @@ export interface McpServerInfo {
     name?: string;
     url?: string;
 }
-export interface VirtualKey {
-    key: string;
-    token?: string;
-    key_alias?: string;
-    created_at: string;
-    expires_at?: string;
-    spend: number;
-    max_budget?: number;
-    budget_duration?: string;
-    tpm_limit?: number;
-    rpm_limit?: number;
-    models?: string[];
-    user_id?: string;
-    /** Team the key is bound to, when any (used to scope the model picker). */
-    team_id?: string;
-    blocked?: boolean;
-}
-export interface ModelInfo {
-    model_name: string;
-    mode: string;
-    supports_function_calling?: boolean;
-    supports_vision?: boolean;
-    input_cost_per_token?: number;
-    output_cost_per_token?: number;
-    max_input_tokens?: number;
-    max_output_tokens?: number;
-    /** Access group names this model belongs to (litellm.model_info.access_groups). A team's `models` list can reference a group name instead of a literal model_name. */
-    access_groups?: string[];
-}
-export interface UsageModelBreakdown {
-    total_spend: number;
-    total_tokens: number;
-    prompt_tokens: number;
-    completion_tokens: number;
-    api_requests: number;
-    successful_requests: number;
-    failed_requests: number;
-}
-export interface UsageKeyBreakdown {
-    key_alias?: string;
-    team_id?: string | null;
-    models: string[];
-    total_spend: number;
-    total_tokens: number;
-    prompt_tokens: number;
-    completion_tokens: number;
-    api_requests: number;
-    successful_requests: number;
-    failed_requests: number;
-}
-export interface UsageDailyPoint {
-    date: string;
-    spend: number;
-    total_tokens: number;
-    prompt_tokens: number;
-    completion_tokens: number;
-    api_requests: number;
-    successful_requests: number;
-    failed_requests: number;
-}
-export interface UsageDailyModelPoint {
-    date: string;
-    model: string;
-    spend: number;
-    prompt_tokens: number;
-    completion_tokens: number;
-    total_tokens: number;
-    api_requests: number;
-    successful_requests: number;
-    failed_requests: number;
-}
-export interface UsageMetrics {
-    total_spend: number;
-    total_tokens: number;
-    prompt_tokens: number;
-    completion_tokens: number;
-    api_requests: number;
-    successful_requests: number;
-    failed_requests: number;
-    usage_by_model: Record<string, UsageModelBreakdown>;
-    usage_by_key: Record<string, UsageKeyBreakdown>;
-    daily_usage: UsageDailyPoint[];
-    daily_by_model: UsageDailyModelPoint[];
-}
-export interface GenerateKeyRequest {
-    alias?: string;
-    models?: string[];
-    team_id?: string;
-    duration?: string;
-    /** Positive number caps spend; null/undefined means unlimited. */
-    max_budget?: number | null;
-    tpm_limit?: number;
-    rpm_limit?: number;
-    key_type?: string;
-}
-export interface UpdateKeyRequest {
-    key_alias?: string;
-    models?: string[];
-    /** Positive number caps spend; null clears it (unlimited, gated by allowUnlimitedBudget). */
-    max_budget?: number | null;
-    tpm_limit?: number;
-    rpm_limit?: number;
-    team_id?: string;
-    duration?: string;
-}
-export interface GenerateKeyResponse {
-    key: string;
-    key_alias?: string;
-    expires_at?: string;
-    max_budget?: number;
-}
 export interface LiteLlmConfig {
-    /** Publicly reachable LiteLLM proxy base URL (for snippet generation). */
-    baseUrl: string;
+    /** Publicly reachable LiteLLM proxy base URL (for snippet generation). Null if not configured. */
+    baseUrl: string | null;
+    /** Support contact for unprovisioned users (optional, e.g. 'admin@example.com' or 'Slack #support'). */
+    supportContact?: string;
     /** Controls for the "Generate New Key" form, set via litellm.keyGeneration in app-config.yaml. */
     keyGeneration?: {
         /** When false (default), the "Unlimited budget" checkbox is hidden and a budget is always required. */
@@ -173,6 +20,11 @@ export interface LiteLlmConfig {
         /** When true (default), a team must be selected before a key can be generated. */
         teamRequired: boolean;
     };
+    /** Controls for key actions, set via litellm.keyActions in app-config.yaml. */
+    keyActions?: {
+        /** Whether key owners can reset their key's spend via the frontend (gated by litellm.key.resetSpend permission). */
+        allowOwnerResetSpend?: boolean;
+    };
     /** Team-management surface controls, set via litellm.teamAdmin in app-config.yaml. */
     teamManagement?: {
         /** True only when the permission framework is enabled AND an admin group is configured. */
@@ -196,33 +48,6 @@ export interface DateRange {
     start: Date;
     end: Date;
 }
-export interface AuditLogEntry {
-    id: string;
-    updated_at: string;
-    changed_by?: string;
-    changed_by_api_key?: string;
-    action?: string;
-    table_name?: string;
-    object_id?: string;
-    before_value?: Record<string, unknown> | null;
-    updated_values?: Record<string, unknown> | null;
-}
-export interface PaginatedAuditLogs {
-    audit_logs: AuditLogEntry[];
-    total: number;
-    page: number;
-    page_size: number;
-    total_pages: number;
-}
-export interface AuditLogsParams {
-    page?: number;
-    page_size?: number;
-    start_date?: string;
-    end_date?: string;
-    action?: string;
-    table_name?: string;
-    changed_by?: string;
-}
 export interface CreateTeamRequest {
     team_alias: string;
     models: string[];
@@ -230,6 +55,11 @@ export interface CreateTeamRequest {
     budget_duration?: string;
     tpm_limit?: number;
     rpm_limit?: number;
+    /**
+     * Optimistic concurrency: the `metadata.updated_at_iso` the edit was based on.
+     * The server answers 409 when the stored value has moved on.
+     */
+    expectedUpdatedAtIso?: string;
 }
 export interface UpdateTeamRequest {
     team_alias?: string;
@@ -240,7 +70,3 @@ export interface UpdateTeamRequest {
     tpm_limit?: number;
     rpm_limit?: number;
 }
-export interface CreateTeamResponse {
-    team_id: string;
-    team_alias?: string;
-}

package/dist/unprovisionedCopy.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Copy for unprovisioned users.
+ */
+export declare function getUnprovisionedTitle(): string;
+export declare function getUnprovisionedMessage(supportContact?: string): string;
+export declare function getAdminDetailsTitle(): string;
+export declare function getAdminDetailsMessage(): string;

package/dist/widgetState.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Widget state machine for loading, error, and ready states.
+ *
+ * Discriminated union that represents the overall state of a widget:
+ * - 'loading': profile or usage data is being fetched
+ * - 'unprovisioned': user has no LiteLLM account (provisioning error)
+ * - 'error': a data fetch failed (non-provisioning error)
+ * - 'ready': data is available; usageUnavailable indicates failed usage fetch
+ */
+export declare const USAGE_UNAVAILABLE_MSG = "Usage unavailable";
+export declare const UNPROVISIONED_MSG = "LiteLLM account not set up. Ask your admin.";
+/**
+ * Detects whether an error represents a provisioning error.
+ *
+ * The backend answers 404 with body `{ error: 'User not found in LiteLLM' }`
+ * when the user hasn't been provisioned. `ApiError` uses that `error` text as
+ * its message, and `useLiteLLMProfile` surfaces failures as a plain message
+ * string, so all three shapes are recognised: an ApiError (status + body), an
+ * Error, or the bare message string.
+ */
+export declare function isUnprovisionedError(error: unknown): boolean;
+export type WidgetViewState = {
+    kind: 'loading';
+} | {
+    kind: 'unprovisioned';
+} | {
+    kind: 'error';
+    message: string;
+} | {
+    kind: 'ready';
+    usageUnavailable: boolean;
+};
+export interface WidgetStateParams {
+    /** True if profile data is currently loading */
+    loading: boolean;
+    /** Error from profile fetch (getUserInfo). null if no error. */
+    error: unknown;
+    /** User info object; null if not loaded or unprovisioned */
+    userInfo: unknown;
+    /** Error from usage fetch. null if no error. */
+    usageError: unknown;
+    /** Number of keys; optional. Used to determine if the user has any keys. */
+    hasKeys?: boolean;
+}
+/**
+ * Determines the overall widget view state based on loading and error conditions.
+ *
+ * Priority:
+ * 1. If loading, return 'loading'
+ * 2. If profile error is unprovisioned, return 'unprovisioned'
+ * 3. If profile error (any other), return 'error'
+ * 4. Otherwise, return 'ready' with usageUnavailable flag based on usageError
+ */
+export declare function widgetViewState({ loading, error, userInfo: _userInfo, usageError, hasKeys: _hasKeys, }: WidgetStateParams): WidgetViewState;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acarmisc/backstage-plugin-litellm",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "backstage": {
     "role": "frontend-plugin",
     "pluginId": "litellm",
@@ -34,12 +34,13 @@
   "scripts": {
     "build": "node build.js && tsc -p tsconfig.json",
     "lint": "eslint src dev --ext .ts,.tsx",
-    "test": "tsc -p tsconfig.test.json && node --test dist-test/**/*.test.js dist-test/*.test.js",
+    "test": "tsc -p tsconfig.test.json && node --import ./test-support/register.mjs --test --test-timeout=30000 \"dist-test/**/*.test.js\"",
     "api-report": "npm run build && api-extractor run --local --verbose",
     "prepack": "npm run build",
     "postpack": ""
   },
   "dependencies": {
+    "@acarmisc/backstage-plugin-litellm-common": "0.1.0",
     "@backstage/catalog-model": "^1.9.0",
     "@backstage/core-components": "^0.18.10",
     "@backstage/core-plugin-api": "^1.12.6",
@@ -69,9 +70,11 @@
     "@testing-library/jest-dom": "^6.0.0",
     "@testing-library/react": "^16.0.0",
     "@testing-library/user-event": "^14.0.0",
+    "@types/jsdom": "^30.0.0",
     "@types/node": "^20.19.43",
     "@types/react": "^18.2.0",
     "esbuild": "^0.28.0",
+    "jsdom": "^26.1.0",
     "react-dom": "^18.2.0",
     "react-router-dom": "^6.30.0",
     "typescript": "^5.9.3"

package/dist/api.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/budget.test.d.ts

@@ -1 +0,0 @@
-export {};