@acarmisc/backstage-plugin-litellm-backend 0.18.0 → 0.20.0

package/dist/teamMemberUsage.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readMemberBreakdownConfig = readMemberBreakdownConfig;
+exports.memberEmails = memberEmails;
+exports.buildTeamMemberUsage = buildTeamMemberUsage;
+exports.redactTeamMemberUsage = redactTeamMemberUsage;
+function readMemberBreakdownConfig(config) {
+    return {
+        enabled: config.getOptionalBoolean('litellm.teamUsage.memberBreakdown.enabled') ?? false,
+        viewerRoles: config.getOptionalStringArray('litellm.teamUsage.memberBreakdown.viewerRoles') ?? [],
+        permissionEnabled: config.getOptionalBoolean('permission.enabled') ?? false,
+    };
+}
+/**
+ * Emails worth looking up in the catalog for the members of a breakdown:
+ * the team roster's emails and email-shaped user ids.
+ */
+function memberEmails(team, keys) {
+    const emails = new Set();
+    for (const m of team.members_with_roles ?? []) {
+        if (m.user_email)
+            emails.add(m.user_email.toLowerCase());
+        else if (m.user_id?.includes('@'))
+            emails.add(m.user_id.toLowerCase());
+    }
+    for (const k of keys) {
+        if (k.user_id?.includes('@'))
+            emails.add(k.user_id.toLowerCase());
+    }
+    return [...emails];
+}
+/**
+ * Attributes a team's usage to its members. Each key in the team's daily
+ * activity is credited to the key's owner (from `/key/list?team_id=`), so the
+ * rows add up to the team total. Activity of keys with no known owner
+ * (deleted keys, keys without a user) lands in one `user_id: null` row.
+ * Team members without activity get zero rows.
+ */
+function buildTeamMemberUsage(teamId, usage, keys, team, profiles = new Map()) {
+    const rows = new Map();
+    const rowFor = (userId) => {
+        let row = rows.get(userId);
+        if (!row) {
+            row = {
+                user_id: userId,
+                spend: 0,
+                spend_share_pct: 0,
+                prompt_tokens: 0,
+                completion_tokens: 0,
+                total_tokens: 0,
+                api_requests: 0,
+                successful_requests: 0,
+                failed_requests: 0,
+                success_rate: null,
+                key_count: 0,
+            };
+            rows.set(userId, row);
+        }
+        return row;
+    };
+    for (const m of team.members_with_roles ?? []) {
+        if (!m.user_id)
+            continue;
+        const row = rowFor(m.user_id);
+        row.role = m.role;
+        if (m.user_email)
+            row.user_email = m.user_email;
+    }
+    const ownerByKey = new Map();
+    for (const k of keys) {
+        if (!k.user_id || !k.token)
+            continue;
+        ownerByKey.set(k.token, k.user_id);
+        rowFor(k.user_id).key_count += 1;
+    }
+    for (const [keyHash, k] of Object.entries(usage.usage_by_key ?? {})) {
+        const row = rowFor(ownerByKey.get(keyHash) ?? null);
+        row.spend += k.total_spend ?? 0;
+        row.prompt_tokens += k.prompt_tokens ?? 0;
+        row.completion_tokens += k.completion_tokens ?? 0;
+        row.total_tokens += k.total_tokens ?? 0;
+        row.api_requests += k.api_requests ?? 0;
+        row.successful_requests += k.successful_requests ?? 0;
+        row.failed_requests += k.failed_requests ?? 0;
+    }
+    const members = [...rows.values()];
+    const totalSpend = members.reduce((sum, r) => sum + r.spend, 0);
+    for (const row of members) {
+        row.spend_share_pct = totalSpend > 0 ? (row.spend / totalSpend) * 100 : 0;
+        const finished = row.successful_requests + row.failed_requests;
+        row.success_rate = finished > 0 ? (row.successful_requests / finished) * 100 : null;
+        if (!row.user_email && row.user_id?.includes('@'))
+            row.user_email = row.user_id;
+        const profile = row.user_email && profiles.get(row.user_email.toLowerCase());
+        if (profile && profile.displayName)
+            row.display_name = profile.displayName;
+    }
+    members.sort((a, b) => b.spend - a.spend ||
+        b.total_tokens - a.total_tokens ||
+        String(a.user_id ?? '￿').localeCompare(String(b.user_id ?? '￿')));
+    return { team_id: teamId, total_spend: totalSpend, members };
+}
+/**
+ * Hides dollar amounts: spend becomes 0 and `spend_share_pct` remains the
+ * way to compare members. Tokens and requests are kept.
+ */
+function redactTeamMemberUsage(usage) {
+    return {
+        ...usage,
+        total_spend: 0,
+        budget_hidden: true,
+        members: usage.members.map(m => ({ ...m, spend: 0 })),
+    };
+}

package/dist/types.cjs.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/types.ts"],
-  "sourcesContent": ["// Re-export common types for backward compatibility\nexport {\n  type UserInfo,\n  type TeamMember,\n  type TeamObjectPermission,\n  type TeamInfo,\n  type CreateTeamResponse,\n  type VirtualKey,\n  type ModelInfo,\n  type UsageModelBreakdown,\n  type UsageKeyBreakdown,\n  type UsageDailyPoint,\n  type UsageDailyModelPoint,\n  type UsageMetrics,\n  type GenerateKeyRequest,\n  type UpdateKeyRequest,\n  type GenerateKeyResponse,\n  type AuditLogEntry,\n  type PaginatedAuditLogs,\n} from '@acarmisc/backstage-plugin-litellm-common';\n\nexport interface CreateTeamRequest {\n  team_alias: string;\n  models?: string[];\n  max_budget?: number;\n  budget_duration?: string;\n  tpm_limit?: number;\n  rpm_limit?: number;\n  metadata?: Record<string, unknown>;\n  object_permission?: {\n    vector_stores?: string[];\n    mcp_servers?: string[];\n    mcp_access_groups?: string[];\n  };\n}\n\nexport interface UpdateTeamRequest extends Partial<CreateTeamRequest> {\n  team_id: string;\n  blocked?: boolean;\n}\n\n/**\n * Shape of a single entry inside LiteLLM's `/user/info` `keys` array.\n * Differs from VirtualKey: uses `expires` (not `expires_at`), exposes\n * both a hashed `token` and a masked `key_name`, and fields are nullable\n * rather than optional.\n */\nexport interface LiteLLMUserKey {\n  token: string;\n  key_name?: string;\n  key_alias?: string | null;\n  spend?: number;\n  expires?: string | null;\n  models?: string[];\n  tpm_limit?: number | null;\n  rpm_limit?: number | null;\n  max_budget?: number | null;\n  budget_duration?: string | null;\n  user_id?: string | null;\n  team_id?: string | null;\n  created_at: string;\n  blocked?: boolean | null;\n  /** Arbitrary metadata stored on the key record. */\n  metadata?: Record<string, unknown> | null;\n}\n\nexport interface DeleteKeyRequest {\n  keys: string[];\n}\n\nexport interface LiteLLMConfig {\n  baseUrl: string;\n  masterKey: string;\n}\n\nexport interface ProvisioningDefaults {\n  maxBudget: number;\n  budgetDuration: string;\n  models: string[];\n  teams: string[];\n  tpmLimit?: number;\n  rpmLimit?: number;\n  /**\n   * LiteLLM user role applied on /user/new. Defaults to \"internal_user\"\n   * which grants self-service Create/Delete/View on the user's own keys.\n   * Valid values: proxy_admin, proxy_admin_viewer, internal_user,\n   * internal_user_viewer, team.\n   */\n  userRole?: string;\n  metadata: Record<string, string>;\n}\n\nexport interface RoleConfig {\n  group: string;\n  maxBudget?: number;\n  budgetDuration?: string;\n  models?: string[];\n  teams?: string[];\n  tpmLimit?: number;\n  rpmLimit?: number;\n  userRole?: string;\n  metadata?: Record<string, string>;\n}\n\nexport interface CreateUserRequest {\n  user_id: string;\n  user_email?: string;\n  user_alias?: string;\n  user_role?: string;\n  max_budget?: number;\n  budget_duration?: string;\n  models?: string[];\n  teams?: string[];\n  tpm_limit?: number;\n  rpm_limit?: number;\n  metadata?: Record<string, string>;\n  auto_create_key?: boolean;\n}\n\nexport interface CreateUserResponse {\n  user_id: string;\n  user_email?: string;\n  max_budget?: number;\n  models?: string[];\n  teams?: string[];\n}\n\n/** One row from LiteLLM's `/spend/logs` (per-request spend log entry). */\nexport interface SpendLogEntry {\n  request_id?: string;\n  /** ISO timestamp of the call. */\n  startTime?: string;\n  endTime?: string;\n  spend?: number;\n  total_tokens?: number;\n  prompt_tokens?: number;\n  completion_tokens?: number;\n  model?: string;\n  /** Virtual key alias or hash the request was billed to. */\n  api_key?: string;\n  user?: string;\n  team_id?: string;\n  /**\n   * Tags attached to the request (e.g. `channel:backstage`,\n   * `session:<thread>`, `invoked-by:<user>`). Shape varies across LiteLLM\n   * versions (array or object) and is normalised to a string[].\n   */\n  request_tags?: string[] | Record<string, string>;\n  /** LiteLLM `metadata` blob; carries trace ids and session grouping. */\n  metadata?: Record<string, unknown> | string | null;\n}\n\nexport interface SpendLogsParams {\n  /** ISO date `YYYY-MM-DD` (inclusive). */\n  start_date: string;\n  /** ISO date `YYYY-MM-DD` (inclusive). */\n  end_date: string;\n  /** Restrict to the given virtual key. */\n  api_key?: string;\n  user_id?: string;\n  team_id?: string;\n  /** Max rows to return (LiteLLM caps at 1000 per page). */\n  page_size?: number;\n}\n\nexport interface AuditLogsParams {\n  page?: number;\n  page_size?: number;\n  start_date?: string;\n  end_date?: string;\n  action?: string;\n  table_name?: string;\n  changed_by?: string;\n  sort_by?: string;\n  sort_order?: 'asc' | 'desc';\n}\n"],
+  "sourcesContent": ["// Re-export common types for backward compatibility\nexport {\n  type UserInfo,\n  type TeamMember,\n  type TeamObjectPermission,\n  type TeamInfo,\n  type CreateTeamResponse,\n  type VirtualKey,\n  type ModelInfo,\n  type UsageModelBreakdown,\n  type UsageKeyBreakdown,\n  type UsageDailyPoint,\n  type UsageDailyModelPoint,\n  type UsageMetrics,\n  type TeamMemberUsage,\n  type TeamMemberUsageRow,\n  type GenerateKeyRequest,\n  type UpdateKeyRequest,\n  type GenerateKeyResponse,\n  type AuditLogEntry,\n  type PaginatedAuditLogs,\n} from '@acarmisc/backstage-plugin-litellm-common';\n\nexport interface CreateTeamRequest {\n  team_alias: string;\n  models?: string[];\n  max_budget?: number;\n  budget_duration?: string;\n  tpm_limit?: number;\n  rpm_limit?: number;\n  metadata?: Record<string, unknown>;\n  object_permission?: {\n    vector_stores?: string[];\n    mcp_servers?: string[];\n    mcp_access_groups?: string[];\n  };\n}\n\nexport interface UpdateTeamRequest extends Partial<CreateTeamRequest> {\n  team_id: string;\n  blocked?: boolean;\n}\n\n/**\n * Shape of a single entry inside LiteLLM's `/user/info` `keys` array.\n * Differs from VirtualKey: uses `expires` (not `expires_at`), exposes\n * both a hashed `token` and a masked `key_name`, and fields are nullable\n * rather than optional.\n */\nexport interface LiteLLMUserKey {\n  token: string;\n  key_name?: string;\n  key_alias?: string | null;\n  spend?: number;\n  expires?: string | null;\n  models?: string[];\n  tpm_limit?: number | null;\n  rpm_limit?: number | null;\n  max_budget?: number | null;\n  budget_duration?: string | null;\n  user_id?: string | null;\n  team_id?: string | null;\n  created_at: string;\n  blocked?: boolean | null;\n  /** Arbitrary metadata stored on the key record. */\n  metadata?: Record<string, unknown> | null;\n}\n\nexport interface DeleteKeyRequest {\n  keys: string[];\n}\n\nexport interface LiteLLMConfig {\n  baseUrl: string;\n  masterKey: string;\n}\n\nexport interface ProvisioningDefaults {\n  maxBudget: number;\n  budgetDuration: string;\n  models: string[];\n  teams: string[];\n  tpmLimit?: number;\n  rpmLimit?: number;\n  /**\n   * LiteLLM user role applied on /user/new. Defaults to \"internal_user\"\n   * which grants self-service Create/Delete/View on the user's own keys.\n   * Valid values: proxy_admin, proxy_admin_viewer, internal_user,\n   * internal_user_viewer, team.\n   */\n  userRole?: string;\n  metadata: Record<string, string>;\n}\n\nexport interface RoleConfig {\n  group: string;\n  maxBudget?: number;\n  budgetDuration?: string;\n  models?: string[];\n  teams?: string[];\n  tpmLimit?: number;\n  rpmLimit?: number;\n  userRole?: string;\n  metadata?: Record<string, string>;\n}\n\nexport interface CreateUserRequest {\n  user_id: string;\n  user_email?: string;\n  user_alias?: string;\n  user_role?: string;\n  max_budget?: number;\n  budget_duration?: string;\n  models?: string[];\n  teams?: string[];\n  tpm_limit?: number;\n  rpm_limit?: number;\n  metadata?: Record<string, string>;\n  auto_create_key?: boolean;\n}\n\nexport interface CreateUserResponse {\n  user_id: string;\n  user_email?: string;\n  max_budget?: number;\n  models?: string[];\n  teams?: string[];\n}\n\n\nexport interface AuditLogsParams {\n  page?: number;\n  page_size?: number;\n  start_date?: string;\n  end_date?: string;\n  action?: string;\n  table_name?: string;\n  changed_by?: string;\n  sort_by?: string;\n  sort_order?: 'asc' | 'desc';\n}\n"],
   "mappings": ";;;;;;;;;;;;;;;;AAAA;AAAA;",
   "names": []
 }

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-export { type UserInfo, type TeamMember, type TeamObjectPermission, type TeamInfo, type CreateTeamResponse, type VirtualKey, type ModelInfo, type UsageModelBreakdown, type UsageKeyBreakdown, type UsageDailyPoint, type UsageDailyModelPoint, type UsageMetrics, type GenerateKeyRequest, type UpdateKeyRequest, type GenerateKeyResponse, type AuditLogEntry, type PaginatedAuditLogs, } from '@acarmisc/backstage-plugin-litellm-common';
+export { type UserInfo, type TeamMember, type TeamObjectPermission, type TeamInfo, type CreateTeamResponse, type VirtualKey, type ModelInfo, type UsageModelBreakdown, type UsageKeyBreakdown, type UsageDailyPoint, type UsageDailyModelPoint, type UsageMetrics, type TeamMemberUsage, type TeamMemberUsageRow, type GenerateKeyRequest, type UpdateKeyRequest, type GenerateKeyResponse, type AuditLogEntry, type PaginatedAuditLogs, } from '@acarmisc/backstage-plugin-litellm-common';
 export interface CreateTeamRequest {
     team_alias: string;
     models?: string[];
@@ -96,42 +96,6 @@ export interface CreateUserResponse {
     models?: string[];
     teams?: string[];
 }
-/** One row from LiteLLM's `/spend/logs` (per-request spend log entry). */
-export interface SpendLogEntry {
-    request_id?: string;
-    /** ISO timestamp of the call. */
-    startTime?: string;
-    endTime?: string;
-    spend?: number;
-    total_tokens?: number;
-    prompt_tokens?: number;
-    completion_tokens?: number;
-    model?: string;
-    /** Virtual key alias or hash the request was billed to. */
-    api_key?: string;
-    user?: string;
-    team_id?: string;
-    /**
-     * Tags attached to the request (e.g. `channel:backstage`,
-     * `session:<thread>`, `invoked-by:<user>`). Shape varies across LiteLLM
-     * versions (array or object) and is normalised to a string[].
-     */
-    request_tags?: string[] | Record<string, string>;
-    /** LiteLLM `metadata` blob; carries trace ids and session grouping. */
-    metadata?: Record<string, unknown> | string | null;
-}
-export interface SpendLogsParams {
-    /** ISO date `YYYY-MM-DD` (inclusive). */
-    start_date: string;
-    /** ISO date `YYYY-MM-DD` (inclusive). */
-    end_date: string;
-    /** Restrict to the given virtual key. */
-    api_key?: string;
-    user_id?: string;
-    team_id?: string;
-    /** Max rows to return (LiteLLM caps at 1000 per page). */
-    page_size?: number;
-}
 export interface AuditLogsParams {
     page?: number;
     page_size?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acarmisc/backstage-plugin-litellm-backend",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "The Backstage backend plugin for LiteLLM governance",
   "backstage": {
     "role": "backend-plugin",
@@ -32,21 +32,17 @@
     "lint": "eslint src --ext .ts",
     "test": "tsc -p tsconfig.test.json && node --test \"dist-test/**/*.test.js\"",
     "api-report": "npm run build && api-extractor run --local --verbose",
-    "prepack": "npm run build",
-    "postpack": ""
+    "prepack": "npm run build"
   },
   "dependencies": {
-    "@acarmisc/backstage-plugin-litellm-common": "0.1.0",
+    "@acarmisc/backstage-plugin-litellm-common": "0.2.0",
     "@backstage/backend-plugin-api": "^1.9.1",
     "@backstage/catalog-client": "^1.9.0",
-    "@backstage/catalog-model": "^1.7.0",
     "@backstage/config": "^1.3.0",
     "@backstage/errors": "^1.3.0",
     "@backstage/plugin-permission-common": "^0.9.10",
-    "@backstage/types": "^1.2.0",
     "express": "^4.18.2",
-    "jose": "^5.9.6",
-    "zod": "^3.22.0"
+    "jose": "^5.9.6"
   },
   "devDependencies": {
     "@backstage/cli": "^0.36.2",