@acarmisc/backstage-plugin-litellm-backend 0.1.2 → 0.1.7

package/config.d.ts

@@ -1,6 +1,101 @@
 export interface Config {
   litellm: {
+    /**
+     * Base URL of the LiteLLM proxy instance.
+     * @visibility backend
+     */
     baseUrl: string;
+
+    /**
+     * LiteLLM master key for admin operations. Never exposed to the frontend.
+     * @visibility secret
+     */
     masterKey: string;
+
+    /**
+     * Email domain appended to the Backstage user entity name to form the
+     * LiteLLM user_id. When set, a user named "john.doe" maps to
+     * "john.doe@<userIdDomain>" in LiteLLM. Omit to use the bare entity name.
+     * @visibility backend
+     */
+    userIdDomain?: string;
+
+    provisioning?: {
+      /**
+       * When true the backend automatically creates a LiteLLM user on first
+       * access if the Backstage user is not yet known to LiteLLM.
+       * Disabled by default — enable explicitly when you are ready.
+       * @default false
+       */
+      enabled?: boolean;
+
+      defaults?: {
+        /**
+         * Max lifetime spend in USD before the account is blocked.
+         * Set a conservative value; null means no hard cap.
+         * @default 10
+         */
+        maxBudget?: number;
+
+        /**
+         * Spend-reset period for maxBudget (e.g. "30d", "7d", "1h").
+         * After this period the spend counter resets.
+         * @default "30d"
+         */
+        budgetDuration?: string;
+
+        /**
+         * LiteLLM model IDs the new user is allowed to call.
+         * Empty array means all models configured in the proxy are allowed.
+         * @default []
+         */
+        models?: string[];
+
+        /**
+         * LiteLLM team IDs to add the new user to automatically.
+         * The user inherits team-level model and budget restrictions.
+         * @default []
+         */
+        teams?: string[];
+
+        /**
+         * Tokens per minute hard cap across all models.
+         * Omit for no limit (team or global limits still apply).
+         */
+        tpmLimit?: number;
+
+        /**
+         * Requests per minute hard cap across all models.
+         * Omit for no limit.
+         */
+        rpmLimit?: number;
+
+        /**
+         * Arbitrary key-value metadata stored on the LiteLLM user record.
+         * Useful for tracking source, cost centre, department, etc.
+         */
+        metadata?: Record<string, string>;
+      };
+
+      /**
+       * Role-based provisioning overrides. Evaluated in order — first match wins.
+       * When a Backstage user belongs to the listed group, these settings override
+       * the defaults above. Fields omitted here fall back to defaults.
+       */
+      roles?: Array<{
+        /**
+         * Backstage group entity ref, e.g. "group:default/ai-power-users".
+         * Matched against the user's memberOf relations in the catalog.
+         */
+        group: string;
+        maxBudget?: number;
+        budgetDuration?: string;
+        models?: string[];
+        teams?: string[];
+        tpmLimit?: number;
+        rpmLimit?: number;
+        metadata?: Record<string, string>;
+      }>;
+    };
   };
-}
+}

package/dist/client.d.ts

@@ -1,11 +1,16 @@
-import { LiteLLMConfig, UserInfo, VirtualKey, ModelInfo, UsageMetrics, TeamInfo, GenerateKeyRequest, GenerateKeyResponse, DeleteKeyRequest } from './types';
+import { LiteLLMConfig, UserInfo, VirtualKey, ModelInfo, UsageMetrics, TeamInfo, GenerateKeyRequest, GenerateKeyResponse, DeleteKeyRequest, CreateUserRequest, CreateUserResponse } from './types';
 export declare class LiteLLMClient {
     private baseUrl;
     private masterKey;
     private timeout;
     constructor(config: LiteLLMConfig, timeout?: number);
     private request;
-    getUserInfo(userId?: string): Promise<UserInfo>;
+    /**
+     * 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>;
     listKeys(userId?: string): Promise<VirtualKey[]>;
     generateKey(request: GenerateKeyRequest): Promise<GenerateKeyResponse>;
     deleteKeys(request: DeleteKeyRequest): Promise<{

package/dist/client.js

@@ -23,7 +23,9 @@ class LiteLLMClient {
             });
             if (!response.ok) {
                 const errorBody = await response.text();
-                throw new Error(`LiteLLM API error: ${response.status} ${response.statusText} - ${errorBody}`);
+                const err = new Error(`LiteLLM API error: ${response.status} ${response.statusText} - ${errorBody}`);
+                err.status = response.status;
+                throw err;
             }
             return response.json();
         }
@@ -31,9 +33,26 @@ class LiteLLMClient {
             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)}` : '';
-        return this.request(`/user/info${query}`);
+        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)}` : '';