@acarmisc/backstage-plugin-litellm-backend 0.1.16 → 0.2.1

package/dist/client.d.ts

@@ -0,0 +1,69 @@
+import { LiteLLMConfig, UserInfo, VirtualKey, ModelInfo, UsageMetrics, TeamInfo, GenerateKeyRequest, GenerateKeyResponse, UpdateKeyRequest, DeleteKeyRequest, CreateUserRequest, CreateUserResponse } from './types';
+export declare class LiteLLMClient {
+    private baseUrl;
+    private masterKey;
+    private timeout;
+    constructor(config: LiteLLMConfig, timeout?: number);
+    private request;
+    /**
+     * Returns null when the user is not found in LiteLLM (404).
+     * Throws on all other errors so callers know something went wrong.
+     */
+    getUserInfo(userId?: string): Promise<UserInfo | null>;
+    createUser(payload: CreateUserRequest): Promise<CreateUserResponse>;
+    /**
+     * Updates an existing LiteLLM user record. Used as a defensive follow-up
+     * after /user/new because the upsert path of /user/new has been observed
+     * to silently drop fields like user_role under concurrent inserts.
+     */
+    updateUser(payload: Partial<CreateUserRequest> & {
+        user_id: string;
+    }): Promise<unknown>;
+    /**
+     * Returns the keys belonging to a user.
+     *
+     * Implementation note: LiteLLM's `/key/info` endpoint requires a `key`
+     * hash and returns 404 when only `user_id` is passed. The correct way
+     * to enumerate a user's keys is `/user/info?user_id=X`, which embeds
+     * a `keys` array with per-key metadata. We unwrap that array and
+     * normalise field names to match the frontend VirtualKey shape
+     * (LiteLLM exposes `key_name` for the masked display value and
+     * `expires` instead of `expires_at`).
+     */
+    listKeys(userId?: string): Promise<VirtualKey[]>;
+    private toVirtualKey;
+    /**
+     * Creates a new virtual key on the LiteLLM proxy.
+     *
+     * Implementation notes — both required to avoid silently-empty keys:
+     *   1. The body must be the plain payload. An earlier version wrapped
+     *      it as `{ json: request }`; LiteLLM doesn't unwrap that envelope
+     *      and treats the request as having no fields, returning a key
+     *      with null alias / models / budget / limits.
+     *   2. LiteLLM expects `key_alias`, not `alias`. Without the rename,
+     *      the alias the user typed is dropped on the floor.
+     */
+    generateKey(request: GenerateKeyRequest): Promise<GenerateKeyResponse>;
+    updateKey(request: UpdateKeyRequest): Promise<VirtualKey>;
+    deleteKeys(request: DeleteKeyRequest): Promise<{
+        success: boolean;
+    }>;
+    listModels(): Promise<ModelInfo[]>;
+    getTeamInfo(teamId: string): Promise<TeamInfo>;
+    private emptyUsage;
+    /**
+     * Transforms LiteLLM's SpendAnalyticsPaginatedResponse into the flatter
+     * UsageMetrics shape consumed by the frontend charts.
+     *
+     * Source shape (per result row):
+     *   { date, metrics, breakdown: { models: { [name]: { metrics, api_key_breakdown: { [keyHash]: { metrics, metadata } } } } } }
+     *
+     * We fan that out into three views the UI consumes:
+     *   - daily_usage     → spend + request trends over time
+     *   - usage_by_model  → which models drove cost / traffic
+     *   - usage_by_key    → which keys drove cost / traffic (with key_alias + team_id from metadata)
+     */
+    private transformDailyActivity;
+    getUsage(startDate: string, endDate: string, userId?: string, _groupBy?: string): Promise<UsageMetrics>;
+    getTeamUsage(teamId: string, startDate: string, endDate: string): Promise<UsageMetrics>;
+}

package/dist/client.js

@@ -0,0 +1,312 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiteLLMClient = void 0;
+const DEFAULT_TIMEOUT = 30000;
+class LiteLLMClient {
+    constructor(config, timeout = DEFAULT_TIMEOUT) {
+        this.baseUrl = config.baseUrl.replace(/\/$/, '');
+        this.masterKey = config.masterKey;
+        this.timeout = timeout;
+    }
+    async request(path, options = {}) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await fetch(`${this.baseUrl}${path}`, {
+                ...options,
+                signal: controller.signal,
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${this.masterKey}`,
+                    ...options.headers,
+                },
+            });
+            if (!response.ok) {
+                const errorBody = await response.text();
+                const err = new Error(`LiteLLM API error: ${response.status} ${response.statusText} - ${errorBody}`);
+                err.status = response.status;
+                throw err;
+            }
+            return response.json();
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    /**
+     * Returns null when the user is not found in LiteLLM (404).
+     * Throws on all other errors so callers know something went wrong.
+     */
+    async getUserInfo(userId) {
+        const query = userId ? `?user_id=${encodeURIComponent(userId)}` : '';
+        try {
+            return await this.request(`/user/info${query}`);
+        }
+        catch (err) {
+            if (err.status === 404)
+                return null;
+            throw err;
+        }
+    }
+    async createUser(payload) {
+        return this.request('/user/new', {
+            method: 'POST',
+            body: JSON.stringify(payload),
+        });
+    }
+    /**
+     * Updates an existing LiteLLM user record. Used as a defensive follow-up
+     * after /user/new because the upsert path of /user/new has been observed
+     * to silently drop fields like user_role under concurrent inserts.
+     */
+    async updateUser(payload) {
+        return this.request('/user/update', {
+            method: 'POST',
+            body: JSON.stringify(payload),
+        });
+    }
+    /**
+     * Returns the keys belonging to a user.
+     *
+     * Implementation note: LiteLLM's `/key/info` endpoint requires a `key`
+     * hash and returns 404 when only `user_id` is passed. The correct way
+     * to enumerate a user's keys is `/user/info?user_id=X`, which embeds
+     * a `keys` array with per-key metadata. We unwrap that array and
+     * normalise field names to match the frontend VirtualKey shape
+     * (LiteLLM exposes `key_name` for the masked display value and
+     * `expires` instead of `expires_at`).
+     */
+    async listKeys(userId) {
+        if (!userId)
+            return [];
+        try {
+            const response = await this.request(`/user/info?user_id=${encodeURIComponent(userId)}`);
+            const rawKeys = response.keys ?? [];
+            return rawKeys.map(this.toVirtualKey);
+        }
+        catch (err) {
+            if (err.status === 404 || err.message.includes('not found')) {
+                return [];
+            }
+            throw err;
+        }
+    }
+    toVirtualKey(k) {
+        return {
+            // The hashed `token` never leaves LiteLLM in a usable form; the
+            // masked `key_name` ("sk-...XXXX") is what the UI displays. Fall
+            // back to `token` only when `key_name` is missing.
+            key: k.key_name ?? k.token,
+            token: k.token,
+            key_alias: k.key_alias ?? undefined,
+            created_at: k.created_at,
+            expires_at: k.expires ?? undefined,
+            spend: k.spend ?? 0,
+            max_budget: k.max_budget ?? undefined,
+            tpm_limit: k.tpm_limit ?? undefined,
+            rpm_limit: k.rpm_limit ?? undefined,
+            models: k.models ?? [],
+            user_id: k.user_id ?? undefined,
+        };
+    }
+    /**
+     * Creates a new virtual key on the LiteLLM proxy.
+     *
+     * Implementation notes — both required to avoid silently-empty keys:
+     *   1. The body must be the plain payload. An earlier version wrapped
+     *      it as `{ json: request }`; LiteLLM doesn't unwrap that envelope
+     *      and treats the request as having no fields, returning a key
+     *      with null alias / models / budget / limits.
+     *   2. LiteLLM expects `key_alias`, not `alias`. Without the rename,
+     *      the alias the user typed is dropped on the floor.
+     */
+    async generateKey(request) {
+        const { alias, ...rest } = request;
+        const payload = {
+            ...rest,
+            ...(alias && { key_alias: alias }),
+        };
+        return this.request('/key/generate', {
+            method: 'POST',
+            body: JSON.stringify(payload),
+        });
+    }
+    async updateKey(request) {
+        return this.request('/key/update', {
+            method: 'POST',
+            body: JSON.stringify(request),
+        });
+    }
+    async deleteKeys(request) {
+        return this.request('/key/delete', {
+            method: 'POST',
+            body: JSON.stringify(request),
+        });
+    }
+    async listModels() {
+        const response = await this.request('/models');
+        return Array.isArray(response) ? response : response.data ?? [];
+    }
+    async getTeamInfo(teamId) {
+        return this.request(`/team/info?team_id=${encodeURIComponent(teamId)}`);
+    }
+    emptyUsage() {
+        return {
+            total_spend: 0,
+            total_tokens: 0,
+            prompt_tokens: 0,
+            completion_tokens: 0,
+            api_requests: 0,
+            successful_requests: 0,
+            failed_requests: 0,
+            usage_by_model: {},
+            usage_by_key: {},
+            daily_usage: [],
+            daily_by_model: [],
+        };
+    }
+    /**
+     * Transforms LiteLLM's SpendAnalyticsPaginatedResponse into the flatter
+     * UsageMetrics shape consumed by the frontend charts.
+     *
+     * Source shape (per result row):
+     *   { date, metrics, breakdown: { models: { [name]: { metrics, api_key_breakdown: { [keyHash]: { metrics, metadata } } } } } }
+     *
+     * We fan that out into three views the UI consumes:
+     *   - daily_usage     → spend + request trends over time
+     *   - usage_by_model  → which models drove cost / traffic
+     *   - usage_by_key    → which keys drove cost / traffic (with key_alias + team_id from metadata)
+     */
+    transformDailyActivity(response) {
+        const results = Array.isArray(response?.results)
+            ? response.results
+            : [];
+        const meta = response?.metadata ?? {};
+        const daily_usage = results
+            .map(r => ({
+            date: r.date,
+            spend: r.metrics?.spend ?? 0,
+            total_tokens: r.metrics?.total_tokens ?? 0,
+            prompt_tokens: r.metrics?.prompt_tokens ?? 0,
+            completion_tokens: r.metrics?.completion_tokens ?? 0,
+            api_requests: r.metrics?.api_requests ?? 0,
+            successful_requests: r.metrics?.successful_requests ?? 0,
+            failed_requests: r.metrics?.failed_requests ?? 0,
+        }))
+            .sort((a, b) => a.date.localeCompare(b.date));
+        const usage_by_model = {};
+        const usage_by_key = {};
+        const daily_by_model = [];
+        const emptyModelBucket = () => ({
+            total_spend: 0,
+            total_tokens: 0,
+            prompt_tokens: 0,
+            completion_tokens: 0,
+            api_requests: 0,
+            successful_requests: 0,
+            failed_requests: 0,
+        });
+        for (const r of results) {
+            const models = r.breakdown?.models ?? {};
+            for (const [name, entry] of Object.entries(models)) {
+                const m = entry?.metrics ?? {};
+                const bucket = usage_by_model[name] ?? emptyModelBucket();
+                bucket.total_spend += m.spend ?? 0;
+                bucket.total_tokens += m.total_tokens ?? 0;
+                bucket.prompt_tokens += m.prompt_tokens ?? 0;
+                bucket.completion_tokens += m.completion_tokens ?? 0;
+                bucket.api_requests += m.api_requests ?? 0;
+                bucket.successful_requests += m.successful_requests ?? 0;
+                bucket.failed_requests += m.failed_requests ?? 0;
+                usage_by_model[name] = bucket;
+                daily_by_model.push({
+                    date: r.date,
+                    model: name,
+                    spend: m.spend ?? 0,
+                    prompt_tokens: m.prompt_tokens ?? 0,
+                    completion_tokens: m.completion_tokens ?? 0,
+                    total_tokens: m.total_tokens ?? 0,
+                    api_requests: m.api_requests ?? 0,
+                    successful_requests: m.successful_requests ?? 0,
+                    failed_requests: m.failed_requests ?? 0,
+                });
+                const keyMap = entry?.api_key_breakdown ?? {};
+                for (const [keyHash, keyEntry] of Object.entries(keyMap)) {
+                    const km = keyEntry?.metrics ?? {};
+                    const kmeta = keyEntry?.metadata ?? {};
+                    const kb = usage_by_key[keyHash] ?? {
+                        key_alias: kmeta.key_alias,
+                        team_id: kmeta.team_id ?? null,
+                        models: [],
+                        ...emptyModelBucket(),
+                    };
+                    if (!kb.key_alias && kmeta.key_alias)
+                        kb.key_alias = kmeta.key_alias;
+                    if (kb.team_id == null && kmeta.team_id)
+                        kb.team_id = kmeta.team_id;
+                    if (!kb.models.includes(name))
+                        kb.models.push(name);
+                    kb.total_spend += km.spend ?? 0;
+                    kb.total_tokens += km.total_tokens ?? 0;
+                    kb.prompt_tokens += km.prompt_tokens ?? 0;
+                    kb.completion_tokens += km.completion_tokens ?? 0;
+                    kb.api_requests += km.api_requests ?? 0;
+                    kb.successful_requests += km.successful_requests ?? 0;
+                    kb.failed_requests += km.failed_requests ?? 0;
+                    usage_by_key[keyHash] = kb;
+                }
+            }
+        }
+        return {
+            total_spend: meta.total_spend ?? 0,
+            total_tokens: meta.total_tokens ?? 0,
+            prompt_tokens: meta.total_prompt_tokens ?? 0,
+            completion_tokens: meta.total_completion_tokens ?? 0,
+            api_requests: meta.total_api_requests ?? 0,
+            successful_requests: meta.total_successful_requests ?? 0,
+            failed_requests: meta.total_failed_requests ?? 0,
+            usage_by_model,
+            usage_by_key,
+            daily_usage,
+            daily_by_model,
+        };
+    }
+    async getUsage(startDate, endDate, userId, _groupBy) {
+        const params = new URLSearchParams({
+            start_date: startDate,
+            end_date: endDate,
+            page_size: '100',
+        });
+        if (userId)
+            params.append('user_id', userId);
+        try {
+            const response = await this.request(`/user/daily/activity?${params.toString()}`);
+            return this.transformDailyActivity(response);
+        }
+        catch (err) {
+            if (err.status === 404 || err.message.includes('not found')) {
+                return this.emptyUsage();
+            }
+            throw err;
+        }
+    }
+    async getTeamUsage(teamId, startDate, endDate) {
+        const params = new URLSearchParams({
+            start_date: startDate,
+            end_date: endDate,
+            team_ids: teamId,
+            page_size: '100',
+        });
+        try {
+            const response = await this.request(`/team/daily/activity?${params.toString()}`);
+            return this.transformDailyActivity(response);
+        }
+        catch (err) {
+            if (err.status === 404 || err.message.includes('not found')) {
+                return this.emptyUsage();
+            }
+            throw err;
+        }
+    }
+}
+exports.LiteLLMClient = LiteLLMClient;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { litellmPlugin } from './plugin';
+export { litellmPlugin as default } from './plugin';
+export { createRouter } from './router';
+export * from './types';
+export { LiteLLMClient } from './client';

package/dist/index.js

@@ -0,0 +1,26 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LiteLLMClient = exports.createRouter = exports.default = exports.litellmPlugin = void 0;
+var plugin_1 = require("./plugin");
+Object.defineProperty(exports, "litellmPlugin", { enumerable: true, get: function () { return plugin_1.litellmPlugin; } });
+var plugin_2 = require("./plugin");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return plugin_2.litellmPlugin; } });
+var router_1 = require("./router");
+Object.defineProperty(exports, "createRouter", { enumerable: true, get: function () { return router_1.createRouter; } });
+__exportStar(require("./types"), exports);
+var client_1 = require("./client");
+Object.defineProperty(exports, "LiteLLMClient", { enumerable: true, get: function () { return client_1.LiteLLMClient; } });

package/dist/plugin.d.ts

@@ -0,0 +1 @@
+export declare const litellmPlugin: import("@backstage/backend-plugin-api").BackendFeature;

package/dist/plugin.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.litellmPlugin = void 0;
+const backend_plugin_api_1 = require("@backstage/backend-plugin-api");
+const router_1 = require("./router");
+exports.litellmPlugin = (0, backend_plugin_api_1.createBackendPlugin)({
+    pluginId: 'litellm',
+    register(reg) {
+        reg.registerInit({
+            deps: {
+                httpRouter: backend_plugin_api_1.coreServices.httpRouter,
+                config: backend_plugin_api_1.coreServices.rootConfig,
+                logger: backend_plugin_api_1.coreServices.logger,
+                auth: backend_plugin_api_1.coreServices.auth,
+                discovery: backend_plugin_api_1.coreServices.discovery,
+            },
+            async init({ httpRouter, config, logger, auth, discovery }) {
+                const router = await (0, router_1.createRouter)({ config, logger, auth, discovery });
+                httpRouter.use(router);
+            },
+        });
+    },
+});

package/dist/provisioning.d.ts

@@ -0,0 +1,87 @@
+import { Config } from '@backstage/config';
+import { AuthService } from '@backstage/backend-plugin-api';
+import { CatalogClient } from '@backstage/catalog-client';
+import { Request } from 'express';
+import { LiteLLMClient } from './client';
+import { UserInfo, ProvisioningDefaults, RoleConfig } from './types';
+/**
+ * Converts a Backstage user entity ref to a LiteLLM user_id.
+ *
+ * When userIdDomain is configured, the entity name is suffixed with the domain
+ * so that LiteLLM user_ids match the organisation's email addresses:
+ *   "user:default/andrea.carmisciano" + "abstract.it"
+ *   → "andrea.carmisciano@abstract.it"
+ *
+ * Without a domain the bare entity name is returned unchanged, which works for
+ * deployments where LiteLLM users were created with plain usernames.
+ */
+export declare function toLiteLLMUserId(userEntityRef: string, userIdDomain?: string): string;
+/**
+ * Reads the provisioning block from config, applying safe defaults for every
+ * field so the feature works out-of-the-box without any YAML required.
+ *
+ * Safe defaults rationale:
+ *   maxBudget:      $10  — prevents runaway spend on a forgotten test account
+ *   budgetDuration: 30d  — monthly reset, aligns with typical billing cycles
+ *   models:         []   — empty means all proxy models are allowed;
+ *                          restrict here or at team level for tighter control
+ *   teams:          []   — no automatic team assignment; add IDs to enrol users
+ *   tpmLimit:       none — LiteLLM global / team limits still apply
+ *   rpmLimit:       none — same
+ *   metadata:       backstage source tag only
+ */
+export declare function readRoleConfigs(config: Config): RoleConfig[];
+/**
+ * Merges role config over defaults. Role fields override defaults only when explicitly set.
+ */
+export declare function applyRoleOverrides(defaults: ProvisioningDefaults, role: RoleConfig): ProvisioningDefaults;
+export declare function readProvisioningDefaults(config: Config): {
+    enabled: boolean;
+    defaults: ProvisioningDefaults;
+};
+/**
+ * Extracts the authenticated Backstage user identity from the request token.
+ * Returns the userEntityRef (e.g. "user:default/john.doe") or undefined when
+ * the request carries no user credential (service-to-service calls).
+ */
+export declare function resolveUserId(req: Request, auth: AuthService): Promise<string | undefined>;
+/**
+ * Profile data extracted from a Backstage Catalog User entity, used to
+ * populate user_email / user_alias on the LiteLLM record.
+ */
+export interface BackstageUserProfile {
+    email?: string;
+    displayName?: string;
+}
+/**
+ * Looks up the catalog User entity for the authenticated user and returns
+ * the profile block. Returns an empty object when the user has no catalog
+ * entity (e.g. dangerouslyAllowSignInWithoutUserInCatalog was used) — the
+ * caller falls back to deriving identity from userIdDomain.
+ */
+export declare function resolveUserProfile(userEntityRef: string, catalogClient: CatalogClient, auth: AuthService, logger: any): Promise<BackstageUserProfile>;
+/**
+ * Creates a LiteLLM user for the given Backstage identity using the configured
+ * defaults. Returns the UserInfo of the newly created account.
+ */
+export declare function provisionUser(client: LiteLLMClient, userId: string, defaults: ProvisioningDefaults, profile: BackstageUserProfile, backstageEntity: string | undefined, logger: any): Promise<UserInfo | null>;
+export declare class ProvisioningError extends Error {
+    status: number;
+    body: {
+        error: string;
+        hint: string;
+        provisioning: boolean;
+    };
+    constructor(message: string, hint: string, provisioning: boolean, status?: number);
+}
+/**
+ * Ensures the LiteLLM user exists, returning its UserInfo.
+ * When the user is missing and provisioning is enabled, attempts to create it.
+ * When provisioning is disabled, throws a ProvisioningError with a clear message.
+ */
+export declare function getOrProvisionUser(client: LiteLLMClient, tokenEntityRef: string | undefined, userId: string | undefined, provisioningEnabled: boolean, provisioningDefaults: ProvisioningDefaults, roleConfigs: RoleConfig[], catalogClient: CatalogClient, auth: AuthService, logger: any): Promise<UserInfo>;
+/**
+ * Fetches the user's Backstage group memberships and returns the first matching
+ * role config (priority order), or undefined when no role matches.
+ */
+export declare function resolveUserRole(userEntityRef: string, roleConfigs: RoleConfig[], catalogClient: CatalogClient, auth: AuthService, logger: any): Promise<RoleConfig | undefined>;