@acarmisc/backstage-plugin-litellm-backend 0.8.2 → 0.10.0

package/config.d.ts

@@ -148,6 +148,107 @@ export interface Config {
       teamRequired?: boolean;
     };
 
+    /**
+     * Team administration governance. Allows a designated Backstage group to
+     * create and manage LiteLLM teams. The feature is disabled (fail-closed)
+     * when unset — all fields default to empty/false to prevent accidental
+     * delegation of capabilities. Set this block only when you have reviewed
+     * the governance policy and are ready to enable the feature.
+     */
+    teamAdmin?: {
+      /**
+       * Backstage group entity ref whose members may manage teams,
+       * e.g. "group:default/litellm-team-admins".
+       * The plugin ships a group template at catalog/litellm-team-admins.yaml.
+       * When omitted the feature is disabled entirely.
+       * @visibility backend
+       */
+      group?: string;
+
+      /**
+       * LiteLLM model names an admin may assign to a team.
+       * Empty array => none assignable (fail-closed).
+       * @default []
+       * @visibility backend
+       */
+      allowedModels?: string[];
+
+      /**
+       * LiteLLM model access-group names an admin may assign to a team.
+       * References access_groups defined in litellm.model_info configuration.
+       * Empty array => none allowed.
+       * @default []
+       * @visibility backend
+       */
+      allowedModelAccessGroups?: string[];
+
+      /**
+       * Hard USD ceiling for max_budget an admin may set on a team.
+       * When omitted, no admin-settable budget is allowed unless
+       * allowUnlimitedBudget is true.
+       * @visibility backend
+       */
+      maxBudgetCeiling?: number;
+
+      /**
+       * Allow an admin to create a team with no budget cap.
+       * @default false
+       * @visibility backend
+       */
+      allowUnlimitedBudget?: boolean;
+
+      /**
+       * Vector-store ids/names an admin may attach as team knowledge bases.
+       * Empty array => none allowed.
+       * @default []
+       * @visibility backend
+       */
+      allowedVectorStores?: string[];
+
+      /**
+       * MCP server ids/names an admin may attach to a team.
+       * Empty array => none allowed.
+       * @default []
+       * @visibility backend
+       */
+      allowedMcpServers?: string[];
+
+      /**
+       * MCP access-group names an admin may attach to a team.
+       * References access_groups defined in litellm.mcp_info configuration.
+       * Empty array => none allowed.
+       * @default []
+       * @visibility backend
+       */
+      allowedMcpAccessGroups?: string[];
+
+      /**
+       * Allow an admin to delete a team (vs. only block/deactivate).
+       * @default false
+       * @visibility backend
+       */
+      allowTeamDelete?: boolean;
+
+      /**
+       * Object-permission management (attaching knowledge bases / MCP servers
+       * to a team). This is the highest-risk surface — attaching a vector store
+       * exposes its documents to every team key, and attaching an MCP server
+       * grants tool execution. Keep disabled unless a real permission policy
+       * (@backstage-community/plugin-rbac or a custom PermissionPolicy) is
+       * installed and the allowedVectorStores / allowedMcpServers allowlists
+       * are set.
+       */
+      objectPermissions?: {
+        /**
+         * When true, mount the knowledge-base and MCP management routes.
+         * Still gated by the permission framework and the allowlists.
+         * @default false
+         * @visibility backend
+         */
+        enabled?: boolean;
+      };
+    };
+
     bridge?: {
       /**
        * When true, mount the /bridge/keys, /bridge/keys (POST), /bridge/models

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { LiteLLMConfig, UserInfo, VirtualKey, ModelInfo, UsageMetrics, TeamInfo, GenerateKeyRequest, GenerateKeyResponse, UpdateKeyRequest, DeleteKeyRequest, CreateUserRequest, CreateUserResponse, AuditLogsParams, PaginatedAuditLogs } from './types';
+import { LiteLLMConfig, UserInfo, VirtualKey, ModelInfo, UsageMetrics, TeamInfo, GenerateKeyRequest, GenerateKeyResponse, UpdateKeyRequest, DeleteKeyRequest, CreateUserRequest, CreateUserResponse, CreateTeamRequest, CreateTeamResponse, UpdateTeamRequest, AuditLogsParams, PaginatedAuditLogs } from './types';
 /**
  * Typed error for failed upstream LiteLLM responses. Preserves the HTTP
  * status and the structured `param` (e.g. `key_alias`) from the upstream
@@ -89,6 +89,66 @@ export declare class LiteLLMClient {
      * team".
      */
     getTeamInfo(teamId: string): Promise<TeamInfo>;
+    /**
+     * Normalises a single team row into the TeamInfo contract. Tolerates both
+     * the `/team/info` shape (row wrapped in a `team_info` envelope alongside
+     * sibling arrays) and a bare row as returned per-item by `/team/list`.
+     * `metadata` is always surfaced so callers can read `owning_group`.
+     */
+    private toTeamInfo;
+    /**
+     * Lists every team known to the LiteLLM proxy. Tolerates the observed
+     * response shapes — a bare array, `{ teams: [...] }`, or `{ data: [...] }` —
+     * and normalises each row through the same unwrap as `getTeamInfo`.
+     *
+     * This returns the GLOBAL team list and must never be exposed directly to
+     * end users; callers are responsible for scoping the result (e.g. to teams
+     * whose `metadata.owning_group` matches the caller's admin group).
+     */
+    listTeams(): Promise<TeamInfo[]>;
+    createTeam(payload: CreateTeamRequest): Promise<CreateTeamResponse>;
+    updateTeam(payload: UpdateTeamRequest): Promise<unknown>;
+    deleteTeam(teamId: string): Promise<unknown>;
+    blockTeam(teamId: string): Promise<unknown>;
+    unblockTeam(teamId: string): Promise<unknown>;
+    /**
+     * Adds a member to a team. LiteLLM's `/team/member_add` nests the member
+     * under a `member` object; `role` is 'user' or 'admin' (we only ever send
+     * 'user' from Backstage). `max_budget_in_team` optionally caps that member's
+     * spend within the team.
+     */
+    teamMemberAdd(payload: {
+        team_id: string;
+        user_id: string;
+        role?: 'user';
+        max_budget_in_team?: number;
+    }): Promise<unknown>;
+    /** Removes a member from a team via LiteLLM's `/team/member_delete`. */
+    teamMemberDelete(payload: {
+        team_id: string;
+        user_id: string;
+    }): Promise<unknown>;
+    /**
+     * Lists the vector stores (knowledge bases) registered on the LiteLLM proxy.
+     * Tolerates a bare array, `{ data: [...] }`, or `{ vector_stores: [...] }`.
+     * Each entry is normalised to `{ id, name? }` — `id` prefers
+     * `vector_store_id` then `id` then `name`.
+     */
+    listVectorStores(): Promise<Array<{
+        id: string;
+        name?: string;
+    }>>;
+    /**
+     * Lists the MCP servers registered on the LiteLLM proxy. Path is
+     * `/mcp/server/list`; tolerates a bare array, `{ data: [...] }` or
+     * `{ servers: [...] }`. Normalised to `{ id, name?, url? }` — `id` prefers
+     * `server_id` then `id` then `alias`/`name`.
+     */
+    listMcpServers(): Promise<Array<{
+        id: string;
+        name?: string;
+        url?: string;
+    }>>;
     private emptyUsage;
     /**
      * Transforms LiteLLM's SpendAnalyticsPaginatedResponse into the flatter

package/dist/client.js

@@ -300,9 +300,18 @@ class LiteLLMClient {
      */
     async getTeamInfo(teamId) {
         const raw = await this.request(`/team/info?team_id=${encodeURIComponent(teamId)}`);
+        return this.toTeamInfo(raw, teamId);
+    }
+    /**
+     * Normalises a single team row into the TeamInfo contract. Tolerates both
+     * the `/team/info` shape (row wrapped in a `team_info` envelope alongside
+     * sibling arrays) and a bare row as returned per-item by `/team/list`.
+     * `metadata` is always surfaced so callers can read `owning_group`.
+     */
+    toTeamInfo(raw, fallbackId) {
         const inner = raw?.team_info ?? {};
         return {
-            team_id: raw?.team_id ?? inner.team_id ?? teamId,
+            team_id: raw?.team_id ?? inner.team_id ?? fallbackId ?? '',
             team_alias: inner.team_alias ?? raw?.team_alias,
             max_budget: inner.max_budget ?? raw?.max_budget,
             spend: inner.spend ?? raw?.spend ?? 0,
@@ -310,8 +319,135 @@ class LiteLLMClient {
             models: inner.models ?? raw?.models,
             tpm_limit: inner.tpm_limit ?? raw?.tpm_limit,
             rpm_limit: inner.rpm_limit ?? raw?.rpm_limit,
+            metadata: inner.metadata ?? raw?.metadata,
+            object_permission: inner.object_permission ?? raw?.object_permission,
+            blocked: inner.blocked ?? raw?.blocked,
+            team_member_budget: inner.team_member_budget ?? raw?.team_member_budget,
         };
     }
+    /**
+     * Lists every team known to the LiteLLM proxy. Tolerates the observed
+     * response shapes — a bare array, `{ teams: [...] }`, or `{ data: [...] }` —
+     * and normalises each row through the same unwrap as `getTeamInfo`.
+     *
+     * This returns the GLOBAL team list and must never be exposed directly to
+     * end users; callers are responsible for scoping the result (e.g. to teams
+     * whose `metadata.owning_group` matches the caller's admin group).
+     */
+    async listTeams() {
+        const raw = await this.request('/team/list');
+        let rows = [];
+        if (Array.isArray(raw))
+            rows = raw;
+        else if (Array.isArray(raw?.teams))
+            rows = raw.teams;
+        else if (Array.isArray(raw?.data))
+            rows = raw.data;
+        return rows.map(row => this.toTeamInfo(row));
+    }
+    async createTeam(payload) {
+        return this.request('/team/new', {
+            method: 'POST',
+            body: JSON.stringify(payload),
+        });
+    }
+    async updateTeam(payload) {
+        return this.request('/team/update', {
+            method: 'POST',
+            body: JSON.stringify(payload),
+        });
+    }
+    async deleteTeam(teamId) {
+        return this.request('/team/delete', {
+            method: 'POST',
+            body: JSON.stringify({ team_ids: [teamId] }),
+        });
+    }
+    async blockTeam(teamId) {
+        return this.request('/team/block', {
+            method: 'POST',
+            body: JSON.stringify({ team_id: teamId }),
+        });
+    }
+    async unblockTeam(teamId) {
+        return this.request('/team/unblock', {
+            method: 'POST',
+            body: JSON.stringify({ team_id: teamId }),
+        });
+    }
+    /**
+     * Adds a member to a team. LiteLLM's `/team/member_add` nests the member
+     * under a `member` object; `role` is 'user' or 'admin' (we only ever send
+     * 'user' from Backstage). `max_budget_in_team` optionally caps that member's
+     * spend within the team.
+     */
+    async teamMemberAdd(payload) {
+        return this.request('/team/member_add', {
+            method: 'POST',
+            body: JSON.stringify({
+                team_id: payload.team_id,
+                member: { user_id: payload.user_id, role: payload.role ?? 'user' },
+                ...(payload.max_budget_in_team !== undefined && {
+                    max_budget_in_team: payload.max_budget_in_team,
+                }),
+            }),
+        });
+    }
+    /** Removes a member from a team via LiteLLM's `/team/member_delete`. */
+    async teamMemberDelete(payload) {
+        return this.request('/team/member_delete', {
+            method: 'POST',
+            body: JSON.stringify({
+                team_id: payload.team_id,
+                user_id: payload.user_id,
+            }),
+        });
+    }
+    /**
+     * Lists the vector stores (knowledge bases) registered on the LiteLLM proxy.
+     * Tolerates a bare array, `{ data: [...] }`, or `{ vector_stores: [...] }`.
+     * Each entry is normalised to `{ id, name? }` — `id` prefers
+     * `vector_store_id` then `id` then `name`.
+     */
+    async listVectorStores() {
+        const raw = await this.request('/vector_store/list');
+        let rows = [];
+        if (Array.isArray(raw))
+            rows = raw;
+        else if (Array.isArray(raw?.data))
+            rows = raw.data;
+        else if (Array.isArray(raw?.vector_stores))
+            rows = raw.vector_stores;
+        return rows
+            .map(r => ({
+            id: r?.vector_store_id ?? r?.id ?? r?.name ?? '',
+            name: r?.vector_store_name ?? r?.name ?? undefined,
+        }))
+            .filter(r => r.id);
+    }
+    /**
+     * Lists the MCP servers registered on the LiteLLM proxy. Path is
+     * `/mcp/server/list`; tolerates a bare array, `{ data: [...] }` or
+     * `{ servers: [...] }`. Normalised to `{ id, name?, url? }` — `id` prefers
+     * `server_id` then `id` then `alias`/`name`.
+     */
+    async listMcpServers() {
+        const raw = await this.request('/mcp/server/list');
+        let rows = [];
+        if (Array.isArray(raw))
+            rows = raw;
+        else if (Array.isArray(raw?.data))
+            rows = raw.data;
+        else if (Array.isArray(raw?.servers))
+            rows = raw.servers;
+        return rows
+            .map(r => ({
+            id: r?.server_id ?? r?.id ?? r?.alias ?? r?.name ?? '',
+            name: r?.alias ?? r?.name ?? undefined,
+            url: r?.url ?? undefined,
+        }))
+            .filter(r => r.id);
+    }
     emptyUsage() {
         return {
             total_spend: 0,