@acarmisc/backstage-plugin-litellm-backend 0.1.15 → 0.2.0

package/dist/index.esm.js

@@ -0,0 +1,323 @@
+// src/plugin.ts
+import { coreServices, createBackendPlugin } from "@backstage/backend-plugin-api";
+
+// src/router.ts
+import { Router } from "express";
+
+// src/client.ts
+var DEFAULT_TIMEOUT = 3e4;
+var LiteLLMClient = class {
+  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)
+    });
+  }
+  async listKeys(userId) {
+    const query = userId ? `?user_id=${encodeURIComponent(userId)}` : "";
+    const response = await this.request(`/key/info${query}`);
+    return Array.isArray(response) ? response : response.info ?? [];
+  }
+  async generateKey(request) {
+    return this.request("/key/generate", {
+      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)}`);
+  }
+  async getUsage(startDate, endDate, userId, groupBy) {
+    const params = new URLSearchParams({ start_date: startDate, end_date: endDate });
+    if (userId) params.append("user_id", userId);
+    if (groupBy) params.append("group_by", groupBy);
+    return this.request(`/usage/keys?${params.toString()}`);
+  }
+  async getTeamUsage(teamId, startDate, endDate) {
+    const params = new URLSearchParams({ start_date: startDate, end_date: endDate, team_id: teamId });
+    return this.request(`/usage/keys?${params.toString()}`);
+  }
+};
+
+// src/router.ts
+function readProvisioningDefaults(config) {
+  const enabled = config.getOptionalBoolean("litellm.provisioning.enabled") ?? false;
+  const defaults = {
+    maxBudget: config.getOptionalNumber("litellm.provisioning.defaults.maxBudget") ?? 10,
+    budgetDuration: config.getOptionalString("litellm.provisioning.defaults.budgetDuration") ?? "30d",
+    models: config.getOptionalStringArray("litellm.provisioning.defaults.models") ?? [],
+    teams: config.getOptionalStringArray("litellm.provisioning.defaults.teams") ?? [],
+    tpmLimit: config.getOptionalNumber("litellm.provisioning.defaults.tpmLimit"),
+    rpmLimit: config.getOptionalNumber("litellm.provisioning.defaults.rpmLimit"),
+    metadata: config.getOptional("litellm.provisioning.defaults.metadata") ?? {}
+  };
+  return { enabled, defaults };
+}
+async function resolveUserId(req, auth) {
+  const rawToken = req.headers.authorization?.slice(7);
+  if (!rawToken) return void 0;
+  try {
+    const credentials = await auth.authenticate(rawToken);
+    const principal = credentials.principal;
+    if (principal?.type === "user") {
+      return principal.userEntityRef;
+    }
+  } catch {
+  }
+  return void 0;
+}
+async function provisionUser(client, userId, defaults, logger) {
+  const payload = {
+    user_id: userId,
+    max_budget: defaults.maxBudget,
+    budget_duration: defaults.budgetDuration,
+    models: defaults.models,
+    teams: defaults.teams,
+    ...defaults.tpmLimit !== void 0 && { tpm_limit: defaults.tpmLimit },
+    ...defaults.rpmLimit !== void 0 && { rpm_limit: defaults.rpmLimit },
+    metadata: {
+      ...defaults.metadata,
+      provisioned_by: "backstage",
+      provisioned_at: (/* @__PURE__ */ new Date()).toISOString(),
+      backstage_entity: userId
+    }
+  };
+  logger.info(`Provisioning new LiteLLM user for Backstage identity: ${userId}`);
+  try {
+    await client.createUser(payload);
+    return await client.getUserInfo(userId);
+  } catch (err) {
+    logger.error(`Failed to provision LiteLLM user ${userId}: ${err.message}`);
+    return null;
+  }
+}
+async function createRouter(options) {
+  const { config, logger, auth } = options;
+  const baseUrl = config.getString("litellm.baseUrl");
+  const masterKey = config.getString("litellm.masterKey");
+  const client = new LiteLLMClient({ baseUrl, masterKey });
+  const { enabled: provisioningEnabled, defaults: provisioningDefaults } = readProvisioningDefaults(config);
+  if (provisioningEnabled) {
+    logger.info(
+      `LiteLLM auto-provisioning enabled \u2014 defaults: budget=$${provisioningDefaults.maxBudget}/${provisioningDefaults.budgetDuration}, models=${provisioningDefaults.models.length ? provisioningDefaults.models.join(",") : "all"}, teams=[${provisioningDefaults.teams.join(",")}]`
+    );
+  }
+  const router = Router();
+  router.get("/health", (_req, res) => {
+    res.json({ status: "ok", provisioning: provisioningEnabled });
+  });
+  router.get("/user/info", async (req, res) => {
+    try {
+      const tokenUserId = await resolveUserId(req, auth);
+      const userId = tokenUserId ?? req.query.user_id;
+      let userInfo = await client.getUserInfo(userId);
+      if (!userInfo) {
+        if (provisioningEnabled && userId) {
+          userInfo = await provisionUser(client, userId, provisioningDefaults, logger);
+        }
+        if (!userInfo) {
+          res.status(404).json({
+            error: "User not found in LiteLLM",
+            provisioning: provisioningEnabled,
+            hint: provisioningEnabled ? "Provisioning attempted but failed \u2014 check LiteLLM logs" : "Enable litellm.provisioning.enabled in app-config.yaml or create the user manually"
+          });
+          return;
+        }
+      }
+      res.json(userInfo);
+    } catch (error) {
+      logger.error("Failed to fetch user info", error);
+      res.status(500).json({ error: error.message });
+    }
+  });
+  router.get("/keys", async (req, res) => {
+    try {
+      const tokenUserId = await resolveUserId(req, auth);
+      const userId = tokenUserId ?? req.query.user_id;
+      const keys = await client.listKeys(userId);
+      res.json(keys);
+    } catch (error) {
+      logger.error("Failed to list keys", error);
+      res.status(500).json({ error: error.message });
+    }
+  });
+  router.post("/keys/generate", async (req, res) => {
+    try {
+      const tokenUserId = await resolveUserId(req, auth);
+      const request = {
+        ...req.body,
+        ...tokenUserId && { user_id: tokenUserId }
+      };
+      const result = await client.generateKey(request);
+      res.json(result);
+    } catch (error) {
+      logger.error("Failed to generate key", error);
+      res.status(500).json({ error: error.message });
+    }
+  });
+  router.delete("/keys/:keyId", async (req, res) => {
+    try {
+      const { keyId } = req.params;
+      if (!keyId) {
+        res.status(400).json({ error: "keyId is required" });
+        return;
+      }
+      await client.deleteKeys({ keys: [keyId] });
+      res.json({ success: true });
+    } catch (error) {
+      logger.error("Failed to delete key", error);
+      res.status(500).json({ error: error.message });
+    }
+  });
+  router.get("/models", async (_req, res) => {
+    try {
+      const models = await client.listModels();
+      res.json(models);
+    } catch (error) {
+      logger.error("Failed to list models", error);
+      res.status(500).json({ error: error.message });
+    }
+  });
+  router.get("/teams", async (req, res) => {
+    try {
+      const tokenUserId = await resolveUserId(req, auth);
+      const userId = tokenUserId ?? req.query.user_id;
+      const userInfo = await client.getUserInfo(userId);
+      if (!userInfo?.teams?.length) {
+        res.json([]);
+        return;
+      }
+      const teams = await Promise.all(
+        userInfo.teams.map(
+          (teamId) => client.getTeamInfo(teamId).catch((err) => {
+            logger.warn(`Failed to fetch team ${teamId}: ${err.message}`);
+            return null;
+          })
+        )
+      );
+      res.json(teams.filter(Boolean));
+    } catch (error) {
+      logger.error("Failed to fetch teams", error);
+      res.status(500).json({ error: error.message });
+    }
+  });
+  router.get("/teams/:teamId/usage", async (req, res) => {
+    try {
+      const { teamId } = req.params;
+      const { start_date, end_date } = req.query;
+      if (!start_date || !end_date) {
+        res.status(400).json({ error: "start_date and end_date are required" });
+        return;
+      }
+      const usage = await client.getTeamUsage(
+        teamId,
+        start_date,
+        end_date
+      );
+      res.json(usage);
+    } catch (error) {
+      logger.error("Failed to fetch team usage", error);
+      res.status(500).json({ error: error.message });
+    }
+  });
+  router.get("/usage", async (req, res) => {
+    try {
+      const { start_date, end_date, group_by } = req.query;
+      if (!start_date || !end_date) {
+        res.status(400).json({ error: "start_date and end_date are required" });
+        return;
+      }
+      const tokenUserId = await resolveUserId(req, auth);
+      const userId = tokenUserId ?? req.query.user_id;
+      const usage = await client.getUsage(
+        start_date,
+        end_date,
+        userId,
+        group_by
+      );
+      res.json(usage);
+    } catch (error) {
+      logger.error("Failed to fetch usage", error);
+      res.status(500).json({ error: error.message });
+    }
+  });
+  return router;
+}
+
+// src/plugin.ts
+var litellmPlugin = createBackendPlugin({
+  pluginId: "litellm",
+  register(reg) {
+    reg.registerInit({
+      deps: {
+        httpRouter: coreServices.httpRouter,
+        config: coreServices.rootConfig,
+        logger: coreServices.logger,
+        auth: coreServices.auth,
+        discovery: coreServices.discovery
+      },
+      async init({ httpRouter, config, logger, auth }) {
+        const router = await createRouter({ config, logger, auth });
+        httpRouter.use(router);
+      }
+    });
+  }
+});
+export {
+  LiteLLMClient,
+  createRouter,
+  litellmPlugin
+};
+//# sourceMappingURL=index.esm.js.map

package/dist/index.esm.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/plugin.ts", "../src/router.ts", "../src/client.ts"],
+  "sourcesContent": ["import { coreServices, createBackendPlugin } from '@backstage/backend-plugin-api';\nimport { createRouter } from './router';\n\nexport const litellmPlugin = createBackendPlugin({\n  pluginId: 'litellm',\n  register(reg) {\n    reg.registerInit({\n      deps: {\n        httpRouter: coreServices.httpRouter,\n        config: coreServices.rootConfig,\n        logger: coreServices.logger,\n        auth: coreServices.auth,\n        discovery: coreServices.discovery,\n      },\n      async init({ httpRouter, config, logger, auth }) {\n        const router = await createRouter({ config, logger, auth });\n        httpRouter.use(router);\n      },\n    });\n  },\n});\n", "import { Router, Request, Response } from 'express';\nimport { Config } from '@backstage/config';\nimport { AuthService } from '@backstage/backend-plugin-api';\nimport { LiteLLMClient } from './client';\nimport {\n  UserInfo,\n  VirtualKey,\n  ModelInfo,\n  UsageMetrics,\n  TeamInfo,\n  GenerateKeyRequest,\n  GenerateKeyResponse,\n  ProvisioningDefaults,\n} from './types';\n\nexport interface RouterOptions {\n  config: Config;\n  logger: any;\n  auth: AuthService;\n}\n\n/**\n * Reads the provisioning block from config, applying safe defaults for every\n * field so the feature works out-of-the-box without any YAML required.\n *\n * Safe defaults rationale:\n *   maxBudget:      $10  \u2014 prevents runaway spend on a forgotten test account\n *   budgetDuration: 30d  \u2014 monthly reset, aligns with typical billing cycles\n *   models:         []   \u2014 empty means all proxy models are allowed;\n *                          restrict here or at team level for tighter control\n *   teams:          []   \u2014 no automatic team assignment; add IDs to enrol users\n *   tpmLimit:       none \u2014 LiteLLM global / team limits still apply\n *   rpmLimit:       none \u2014 same\n *   metadata:       backstage source tag only\n */\nfunction readProvisioningDefaults(config: Config): { enabled: boolean; defaults: ProvisioningDefaults } {\n  const enabled = config.getOptionalBoolean('litellm.provisioning.enabled') ?? false;\n  const defaults: ProvisioningDefaults = {\n    maxBudget: config.getOptionalNumber('litellm.provisioning.defaults.maxBudget') ?? 10,\n    budgetDuration: config.getOptionalString('litellm.provisioning.defaults.budgetDuration') ?? '30d',\n    models: config.getOptionalStringArray('litellm.provisioning.defaults.models') ?? [],\n    teams: config.getOptionalStringArray('litellm.provisioning.defaults.teams') ?? [],\n    tpmLimit: config.getOptionalNumber('litellm.provisioning.defaults.tpmLimit'),\n    rpmLimit: config.getOptionalNumber('litellm.provisioning.defaults.rpmLimit'),\n    metadata: (config.getOptional<Record<string, string>>('litellm.provisioning.defaults.metadata') ?? {}),\n  };\n  return { enabled, defaults };\n}\n\n/**\n * Extracts the authenticated Backstage user identity from the request token.\n * Returns the userEntityRef (e.g. \"user:default/john.doe\") or undefined when\n * the request carries no user credential (service-to-service calls).\n */\nasync function resolveUserId(req: Request, auth: AuthService): Promise<string | undefined> {\n  const rawToken = req.headers.authorization?.slice(7);\n  if (!rawToken) return undefined;\n  try {\n    const credentials = await auth.authenticate(rawToken);\n    const principal = credentials.principal as any;\n    if (principal?.type === 'user') {\n      return principal.userEntityRef as string;\n    }\n  } catch {\n    // invalid or service token \u2014 caller gets query-param fallback\n  }\n  return undefined;\n}\n\n/**\n * Creates a LiteLLM user for the given Backstage identity using the configured\n * defaults. Returns the UserInfo of the newly created account.\n */\nasync function provisionUser(\n  client: LiteLLMClient,\n  userId: string,\n  defaults: ProvisioningDefaults,\n  logger: any,\n): Promise<UserInfo | null> {\n  const payload = {\n    user_id: userId,\n    max_budget: defaults.maxBudget,\n    budget_duration: defaults.budgetDuration,\n    models: defaults.models,\n    teams: defaults.teams,\n    ...(defaults.tpmLimit !== undefined && { tpm_limit: defaults.tpmLimit }),\n    ...(defaults.rpmLimit !== undefined && { rpm_limit: defaults.rpmLimit }),\n    metadata: {\n      ...defaults.metadata,\n      provisioned_by: 'backstage',\n      provisioned_at: new Date().toISOString(),\n      backstage_entity: userId,\n    },\n  };\n\n  logger.info(`Provisioning new LiteLLM user for Backstage identity: ${userId}`);\n  try {\n    await client.createUser(payload);\n    // Fetch the freshly-created user record to return consistent UserInfo shape\n    return await client.getUserInfo(userId);\n  } catch (err: any) {\n    logger.error(`Failed to provision LiteLLM user ${userId}: ${err.message}`);\n    return null;\n  }\n}\n\nexport async function createRouter(options: RouterOptions): Promise<Router> {\n  const { config, logger, auth } = options;\n\n  const baseUrl = config.getString('litellm.baseUrl');\n  const masterKey = config.getString('litellm.masterKey');\n  const client = new LiteLLMClient({ baseUrl, masterKey });\n  const { enabled: provisioningEnabled, defaults: provisioningDefaults } = readProvisioningDefaults(config);\n\n  if (provisioningEnabled) {\n    logger.info(\n      `LiteLLM auto-provisioning enabled \u2014 defaults: budget=$${provisioningDefaults.maxBudget}/${provisioningDefaults.budgetDuration}, models=${provisioningDefaults.models.length ? provisioningDefaults.models.join(',') : 'all'}, teams=[${provisioningDefaults.teams.join(',')}]`,\n    );\n  }\n\n  const router = Router();\n\n  router.get('/health', (_req: Request, res: Response) => {\n    res.json({ status: 'ok', provisioning: provisioningEnabled });\n  });\n\n  router.get('/user/info', async (req: Request, res: Response) => {\n    try {\n      const tokenUserId = await resolveUserId(req, auth);\n      const userId = tokenUserId ?? (req.query.user_id as string | undefined);\n\n      let userInfo: UserInfo | null = await client.getUserInfo(userId);\n\n      if (!userInfo) {\n        if (provisioningEnabled && userId) {\n          userInfo = await provisionUser(client, userId, provisioningDefaults, logger);\n        }\n\n        if (!userInfo) {\n          res.status(404).json({\n            error: 'User not found in LiteLLM',\n            provisioning: provisioningEnabled,\n            hint: provisioningEnabled\n              ? 'Provisioning attempted but failed \u2014 check LiteLLM logs'\n              : 'Enable litellm.provisioning.enabled in app-config.yaml or create the user manually',\n          });\n          return;\n        }\n      }\n\n      res.json(userInfo);\n    } catch (error: any) {\n      logger.error('Failed to fetch user info', error);\n      res.status(500).json({ error: error.message });\n    }\n  });\n\n  router.get('/keys', async (req: Request, res: Response) => {\n    try {\n      const tokenUserId = await resolveUserId(req, auth);\n      const userId = tokenUserId ?? (req.query.user_id as string | undefined);\n      const keys: VirtualKey[] = await client.listKeys(userId);\n      res.json(keys);\n    } catch (error: any) {\n      logger.error('Failed to list keys', error);\n      res.status(500).json({ error: error.message });\n    }\n  });\n\n  router.post('/keys/generate', async (req: Request, res: Response) => {\n    try {\n      const tokenUserId = await resolveUserId(req, auth);\n      const request: GenerateKeyRequest = {\n        ...req.body,\n        ...(tokenUserId && { user_id: tokenUserId }),\n      };\n      const result: GenerateKeyResponse = await client.generateKey(request);\n      res.json(result);\n    } catch (error: any) {\n      logger.error('Failed to generate key', error);\n      res.status(500).json({ error: error.message });\n    }\n  });\n\n  router.delete('/keys/:keyId', async (req: Request, res: Response) => {\n    try {\n      const { keyId } = req.params;\n      if (!keyId) {\n        res.status(400).json({ error: 'keyId is required' });\n        return;\n      }\n      await client.deleteKeys({ keys: [keyId] });\n      res.json({ success: true });\n    } catch (error: any) {\n      logger.error('Failed to delete key', error);\n      res.status(500).json({ error: error.message });\n    }\n  });\n\n  router.get('/models', async (_req: Request, res: Response) => {\n    try {\n      const models: ModelInfo[] = await client.listModels();\n      res.json(models);\n    } catch (error: any) {\n      logger.error('Failed to list models', error);\n      res.status(500).json({ error: error.message });\n    }\n  });\n\n  router.get('/teams', async (req: Request, res: Response) => {\n    try {\n      const tokenUserId = await resolveUserId(req, auth);\n      const userId = tokenUserId ?? (req.query.user_id as string | undefined);\n      const userInfo: UserInfo | null = await client.getUserInfo(userId);\n\n      if (!userInfo?.teams?.length) {\n        res.json([]);\n        return;\n      }\n\n      const teams = await Promise.all(\n        userInfo.teams.map(teamId =>\n          client.getTeamInfo(teamId).catch(err => {\n            logger.warn(`Failed to fetch team ${teamId}: ${err.message}`);\n            return null;\n          }),\n        ),\n      );\n      res.json(teams.filter(Boolean) as TeamInfo[]);\n    } catch (error: any) {\n      logger.error('Failed to fetch teams', error);\n      res.status(500).json({ error: error.message });\n    }\n  });\n\n  router.get('/teams/:teamId/usage', async (req: Request, res: Response) => {\n    try {\n      const { teamId } = req.params;\n      const { start_date, end_date } = req.query;\n      if (!start_date || !end_date) {\n        res.status(400).json({ error: 'start_date and end_date are required' });\n        return;\n      }\n      const usage: UsageMetrics = await client.getTeamUsage(\n        teamId,\n        start_date as string,\n        end_date as string,\n      );\n      res.json(usage);\n    } catch (error: any) {\n      logger.error('Failed to fetch team usage', error);\n      res.status(500).json({ error: error.message });\n    }\n  });\n\n  router.get('/usage', async (req: Request, res: Response) => {\n    try {\n      const { start_date, end_date, group_by } = req.query;\n      if (!start_date || !end_date) {\n        res.status(400).json({ error: 'start_date and end_date are required' });\n        return;\n      }\n      const tokenUserId = await resolveUserId(req, auth);\n      const userId = tokenUserId ?? (req.query.user_id as string | undefined);\n      const usage: UsageMetrics = await client.getUsage(\n        start_date as string,\n        end_date as string,\n        userId,\n        group_by as string | undefined,\n      );\n      res.json(usage);\n    } catch (error: any) {\n      logger.error('Failed to fetch usage', error);\n      res.status(500).json({ error: error.message });\n    }\n  });\n\n  return router;\n}\n", "import {\n  LiteLLMConfig,\n  UserInfo,\n  VirtualKey,\n  ModelInfo,\n  UsageMetrics,\n  TeamInfo,\n  GenerateKeyRequest,\n  GenerateKeyResponse,\n  DeleteKeyRequest,\n  CreateUserRequest,\n  CreateUserResponse,\n} from './types';\n\nconst DEFAULT_TIMEOUT = 30000;\n\nexport class LiteLLMClient {\n  private baseUrl: string;\n  private masterKey: string;\n  private timeout: number;\n\n  constructor(config: LiteLLMConfig, timeout = DEFAULT_TIMEOUT) {\n    this.baseUrl = config.baseUrl.replace(/\\/$/, '');\n    this.masterKey = config.masterKey;\n    this.timeout = timeout;\n  }\n\n  private async request<T>(path: string, options: RequestInit = {}): Promise<T> {\n    const controller = new AbortController();\n    const timeoutId = setTimeout(() => controller.abort(), this.timeout);\n\n    try {\n      const response = await fetch(`${this.baseUrl}${path}`, {\n        ...options,\n        signal: controller.signal,\n        headers: {\n          'Content-Type': 'application/json',\n          'Authorization': `Bearer ${this.masterKey}`,\n          ...options.headers,\n        },\n      });\n\n      if (!response.ok) {\n        const errorBody = await response.text();\n        const err = new Error(`LiteLLM API error: ${response.status} ${response.statusText} - ${errorBody}`);\n        (err as any).status = response.status;\n        throw err;\n      }\n\n      return response.json();\n    } finally {\n      clearTimeout(timeoutId);\n    }\n  }\n\n  /**\n   * Returns null when the user is not found in LiteLLM (404).\n   * Throws on all other errors so callers know something went wrong.\n   */\n  async getUserInfo(userId?: string): Promise<UserInfo | null> {\n    const query = userId ? `?user_id=${encodeURIComponent(userId)}` : '';\n    try {\n      return await this.request<UserInfo>(`/user/info${query}`);\n    } catch (err: any) {\n      if (err.status === 404) return null;\n      throw err;\n    }\n  }\n\n  async createUser(payload: CreateUserRequest): Promise<CreateUserResponse> {\n    return this.request<CreateUserResponse>('/user/new', {\n      method: 'POST',\n      body: JSON.stringify(payload),\n    });\n  }\n\n  async listKeys(userId?: string): Promise<VirtualKey[]> {\n    const query = userId ? `?user_id=${encodeURIComponent(userId)}` : '';\n    const response = await this.request<{ info: VirtualKey[] } | VirtualKey[]>(`/key/info${query}`);\n    return Array.isArray(response) ? response : (response.info ?? []);\n  }\n\n  async generateKey(request: GenerateKeyRequest): Promise<GenerateKeyResponse> {\n    return this.request<GenerateKeyResponse>('/key/generate', {\n      method: 'POST',\n      body: JSON.stringify(request),\n    });\n  }\n\n  async deleteKeys(request: DeleteKeyRequest): Promise<{ success: boolean }> {\n    return this.request<{ success: boolean }>('/key/delete', {\n      method: 'POST',\n      body: JSON.stringify(request),\n    });\n  }\n\n  async listModels(): Promise<ModelInfo[]> {\n    const response = await this.request<{ data: ModelInfo[] } | ModelInfo[]>('/models');\n    return Array.isArray(response) ? response : (response.data ?? []);\n  }\n\n  async getTeamInfo(teamId: string): Promise<TeamInfo> {\n    return this.request<TeamInfo>(`/team/info?team_id=${encodeURIComponent(teamId)}`);\n  }\n\n  async getUsage(startDate: string, endDate: string, userId?: string, groupBy?: string): Promise<UsageMetrics> {\n    const params = new URLSearchParams({ start_date: startDate, end_date: endDate });\n    if (userId) params.append('user_id', userId);\n    if (groupBy) params.append('group_by', groupBy);\n    return this.request<UsageMetrics>(`/usage/keys?${params.toString()}`);\n  }\n\n  async getTeamUsage(teamId: string, startDate: string, endDate: string): Promise<UsageMetrics> {\n    const params = new URLSearchParams({ start_date: startDate, end_date: endDate, team_id: teamId });\n    return this.request<UsageMetrics>(`/usage/keys?${params.toString()}`);\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/index.js

@@ -0,0 +1,24 @@
+"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.litellmPlugin = void 0;
+var plugin_1 = require("./plugin");
+Object.defineProperty(exports, "litellmPlugin", { enumerable: true, get: function () { return plugin_1.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,72 @@
+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>;
+/**
+ * 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, 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);
+}
+/**
+ * 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>;