nolo-cli 0.1.30 → 0.1.31

package/auth/routes.ts

@@ -37,6 +37,46 @@ export const authRoutes = {
       method: "GET" as const,
       createPath: () => `${API_VERSION}/users`,
     },
+    usageReport: {
+      path: `${API_VERSION}/users/usage-report`,
+      method: "GET" as const,
+      createPath: () => `${API_VERSION}/users/usage-report`,
+    },
+    providerBillingHealth: {
+      path: `${API_VERSION}/users/provider-billing-health`,
+      method: "GET" as const,
+      createPath: () => `${API_VERSION}/users/provider-billing-health`,
+    },
+    providerBillingDrilldown: {
+      path: `${API_VERSION}/users/provider-billing-drilldown`,
+      method: "GET" as const,
+      createPath: () => `${API_VERSION}/users/provider-billing-drilldown`,
+    },
+    providerCredentials: {
+      path: `${API_VERSION}/users/provider-credentials`,
+      method: "GET" as const,
+      createPath: () => `${API_VERSION}/users/provider-credentials`,
+    },
+    providerCredentialLifecycle: {
+      path: `${API_VERSION}/users/provider-credentials/lifecycle`,
+      method: "POST" as const,
+      createPath: () => `${API_VERSION}/users/provider-credentials/lifecycle`,
+    },
+    billingAnomalyLifecycle: {
+      path: `${API_VERSION}/users/billing-anomalies/lifecycle`,
+      method: "POST" as const,
+      createPath: () => `${API_VERSION}/users/billing-anomalies/lifecycle`,
+    },
+    billingAnomalyDrilldown: {
+      path: `${API_VERSION}/users/billing-anomalies/drilldown`,
+      method: "GET" as const,
+      createPath: () => `${API_VERSION}/users/billing-anomalies/drilldown`,
+    },
+    billingAnomalyAudit: {
+      path: `${API_VERSION}/users/billing-anomalies/audit`,
+      method: "POST" as const,
+      createPath: () => `${API_VERSION}/users/billing-anomalies/audit`,
+    },
     detail: {
       path: `${API_VERSION}/users/:userId`,
       method: "GET" as const,
@@ -72,6 +112,12 @@ export const authRoutes = {
       createPath: (params: RouteParams) =>
         `${API_VERSION}/users/${params.userId}/enable`,
     },
+    adminPermissions: {
+      path: `${API_VERSION}/users/:userId/admin-permissions`,
+      method: "POST" as const,
+      createPath: (params: RouteParams) =>
+        `${API_VERSION}/users/${params.userId}/admin-permissions`,
+    },
     sendEmail: {
       path: `${API_VERSION}/users/send-email`,
       method: "POST" as const,

package/auth/server/accessActivity.ts

@@ -1,5 +1,5 @@
 import { DB_PREFIX } from "../../database/keys";
-import serverDb from "../../database/server/db";
+import { getServerAuthorityStore } from "../../database/server/db";
 
 import { balanceLockManager } from "./locks";
 
@@ -116,10 +116,11 @@ export async function recordUserAccessActivity(
 ) {
   const timestamp = options.timestamp ?? Date.now();
   const key = `${DB_PREFIX.USER}${userId}`;
+  const store = getServerAuthorityStore();
   const lock = balanceLockManager.getLock(userId);
 
   await lock.runExclusive(async () => {
-    const user = await serverDb.get(key).catch(() => null);
+    const user = await store.get(key).catch(() => null);
     if (!user) return;
 
     const entry: RecentAccessEntry = {
@@ -129,7 +130,7 @@ export async function recordUserAccessActivity(
       device: summarizeUserAgent(options.userAgent),
     };
 
-    await serverDb.put(key, {
+    await store.put(key, {
       ...user,
       ...(options.updateLastActiveAt ? { lastActiveAt: timestamp } : {}),
       ...(options.updateLastLoginAt ? { lastLoginAt: timestamp } : {}),

package/auth/server/adminPermissions.ts

@@ -0,0 +1,43 @@
+import {
+  checkAdminPermission,
+  createErrorResponse,
+  createSuccessResponse,
+  handleOptionsRequest,
+} from "./shared";
+import { updateUserAdminPermissions } from "./usageManagementAccess";
+
+export async function handleUpdateUserAdminPermissions(req: Request, userId: string) {
+  if (req.method === "OPTIONS") {
+    return handleOptionsRequest();
+  }
+
+  const permissionError = checkAdminPermission(req.user?.userId);
+  if (permissionError) return permissionError;
+
+  if (!userId) {
+    return createErrorResponse("User ID is required", 400);
+  }
+
+  try {
+    const body = await req.json().catch(() => ({}));
+    const usageManagement = body?.usageManagement;
+    if (typeof usageManagement !== "boolean") {
+      return createErrorResponse("usageManagement must be boolean", 400);
+    }
+
+    const updatedUser = await updateUserAdminPermissions(userId, {
+      usageManagement,
+    });
+    if (!updatedUser) {
+      return createErrorResponse("User not found", 404);
+    }
+
+    return createSuccessResponse({
+      success: true,
+      userId,
+      adminPermissions: updatedUser.adminPermissions,
+    });
+  } catch {
+    return createErrorResponse("Failed to update admin permissions");
+  }
+}

package/auth/server/adminUsageReport.ts

@@ -0,0 +1,375 @@
+import { getServerAuthorityStore } from "../../database/server/db";
+import { createAgentKey, createCybotKey, createKey, DB_PREFIX } from "../../database/keys";
+
+import {
+  checkAdminPermission,
+  createErrorResponse,
+  createSuccessResponse,
+  handleOptionsRequest,
+} from "./shared";
+
+export type AdminUsageReportStore = {
+  iterator: (options: { gte?: string; lte?: string }) => AsyncIterable<[string, unknown]>;
+  get?: (key: string) => Promise<unknown>;
+};
+
+export type AdminUsageRankItem = {
+  count: number;
+  cost: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheCreationInputTokens: number;
+  cacheReadInputTokens: number;
+  costRatio: number;
+};
+
+export type AdminUsageReport = {
+  generatedAt: string;
+  sinceMs: number;
+  untilMs: number;
+  limit: number;
+  summary: AdminUsageRankItem & {
+    recordsScanned: number;
+    recordsInWindow: number;
+    totalCost: number;
+  };
+  rankings: {
+    users: (AdminUsageRankItem & {
+      userId: string;
+      username?: string;
+      email?: string;
+    })[];
+    dialogs: (AdminUsageRankItem & {
+      dialogId: string;
+      userId: string;
+      username?: string;
+      title?: string;
+    })[];
+    models: (AdminUsageRankItem & {
+      provider: string;
+      model: string;
+      serviceTier?: string;
+    })[];
+    agents: (AdminUsageRankItem & {
+      agentKey: string;
+      name?: string;
+      title?: string;
+    })[];
+  };
+};
+
+type TokenRecord = {
+  type?: string;
+  userId?: string;
+  username?: string;
+  cybotId?: string;
+  provider?: string;
+  model?: string;
+  billing_service_tier?: string;
+  dialogId?: string;
+  input_tokens?: number;
+  output_tokens?: number;
+  cache_creation_input_tokens?: number;
+  cache_read_input_tokens?: number;
+  cost?: number;
+  timestamp?: number;
+  createdAt?: string | number;
+};
+
+type Accumulator = {
+  count: number;
+  cost: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheCreationInputTokens: number;
+  cacheReadInputTokens: number;
+};
+
+const TOKEN_PREFIX = "token-";
+const TOKEN_STATS_PREFIX = "token-stats-";
+const MAX_LIMIT = 200;
+
+const rangeEnd = (prefix: string) => `${prefix}\uffff`;
+
+const roundMetric = (value: number) => Math.round(value * 1_000_000) / 1_000_000;
+
+const isObjectRecord = (value: unknown): value is Record<string, unknown> =>
+  !!value && typeof value === "object" && !Array.isArray(value);
+
+const toFiniteNumber = (value: unknown, fallback = 0) =>
+  typeof value === "number" && Number.isFinite(value) ? value : fallback;
+
+const normalizeText = (value: unknown, fallback = "unknown") =>
+  typeof value === "string" && value.trim() ? value.trim() : fallback;
+
+const createAccumulator = (): Accumulator => ({
+  count: 0,
+  cost: 0,
+  inputTokens: 0,
+  outputTokens: 0,
+  cacheCreationInputTokens: 0,
+  cacheReadInputTokens: 0,
+});
+
+const addToAccumulator = (acc: Accumulator, record: TokenRecord) => {
+  acc.count += 1;
+  acc.cost += toFiniteNumber(record.cost);
+  acc.inputTokens += toFiniteNumber(record.input_tokens);
+  acc.outputTokens += toFiniteNumber(record.output_tokens);
+  acc.cacheCreationInputTokens += toFiniteNumber(record.cache_creation_input_tokens);
+  acc.cacheReadInputTokens += toFiniteNumber(record.cache_read_input_tokens);
+};
+
+const getTokenTimestamp = (record: TokenRecord) => {
+  if (typeof record.timestamp === "number" && Number.isFinite(record.timestamp)) {
+    return record.timestamp;
+  }
+  if (typeof record.createdAt === "number" && Number.isFinite(record.createdAt)) {
+    return record.createdAt;
+  }
+  if (typeof record.createdAt === "string") {
+    const parsed = Date.parse(record.createdAt);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return null;
+};
+
+const isTokenRecord = (key: string, value: unknown): value is TokenRecord =>
+  key.startsWith(TOKEN_PREFIX) &&
+  !key.startsWith(TOKEN_STATS_PREFIX) &&
+  isObjectRecord(value) &&
+  value.type === "token";
+
+const metricFields = (acc: Accumulator, totalCost: number): AdminUsageRankItem => ({
+  count: acc.count,
+  cost: roundMetric(acc.cost),
+  inputTokens: acc.inputTokens,
+  outputTokens: acc.outputTokens,
+  cacheCreationInputTokens: acc.cacheCreationInputTokens,
+  cacheReadInputTokens: acc.cacheReadInputTokens,
+  costRatio: totalCost > 0 ? roundMetric(acc.cost / totalCost) : 0,
+});
+
+const sortedEntries = <T>(groups: Map<string, T & Accumulator>, limit: number) =>
+  Array.from(groups.entries())
+    .sort(([, a], [, b]) => b.cost - a.cost || b.outputTokens - a.outputTokens || b.count - a.count)
+    .slice(0, limit);
+
+const getOptional = async (store: AdminUsageReportStore, key: string) => {
+  if (!store.get) return null;
+  try {
+    return await store.get(key);
+  } catch {
+    return null;
+  }
+};
+
+const readUserLabel = async (store: AdminUsageReportStore, userId: string) => {
+  const value = await getOptional(store, `${DB_PREFIX.USER}${userId}`);
+  if (!isObjectRecord(value)) return {};
+  return {
+    username: typeof value.username === "string" ? value.username : undefined,
+    email: typeof value.email === "string" ? value.email : undefined,
+  };
+};
+
+const readDialogTitle = async (
+  store: AdminUsageReportStore,
+  userId: string,
+  dialogId: string
+) => {
+  const value = await getOptional(store, createKey("dialog", userId, dialogId));
+  if (!isObjectRecord(value)) return undefined;
+  return typeof value.title === "string" ? value.title : undefined;
+};
+
+const readAgentLabel = async (store: AdminUsageReportStore, agentKey: string) => {
+  const candidateKeys = [agentKey];
+  if (!agentKey.startsWith("agent-") && !agentKey.startsWith("cybot-")) {
+    candidateKeys.push(createAgentKey.public(agentKey), createCybotKey.public(agentKey));
+  }
+
+  for (const key of candidateKeys) {
+    const value = await getOptional(store, key);
+    if (!isObjectRecord(value)) continue;
+    return {
+      name: typeof value.name === "string" ? value.name : undefined,
+      title: typeof value.title === "string" ? value.title : undefined,
+    };
+  }
+
+  return {};
+};
+
+const addGroupRecord = <T extends object>(
+  groups: Map<string, T & Accumulator>,
+  key: string,
+  record: TokenRecord,
+  meta: T
+) => {
+  const existing = groups.get(key);
+  const acc = existing ?? ({ ...meta, ...createAccumulator() } as T & Accumulator);
+  addToAccumulator(acc, record);
+  groups.set(key, acc);
+};
+
+export async function buildAdminUsageReport(args: {
+  store: AdminUsageReportStore;
+  sinceMs: number;
+  untilMs: number;
+  nowMs?: number;
+  limit?: number;
+}): Promise<AdminUsageReport> {
+  const limit = Math.min(MAX_LIMIT, Math.max(1, Math.floor(args.limit ?? 20)));
+  const totals = createAccumulator();
+  const users = new Map<string, { userId: string; username?: string } & Accumulator>();
+  const dialogs = new Map<
+    string,
+    { userId: string; username?: string; dialogId: string } & Accumulator
+  >();
+  const models = new Map<
+    string,
+    { provider: string; model: string; serviceTier?: string } & Accumulator
+  >();
+  const agents = new Map<string, { agentKey: string } & Accumulator>();
+  let recordsScanned = 0;
+
+  for await (const [key, value] of args.store.iterator({
+    gte: TOKEN_PREFIX,
+    lte: rangeEnd(TOKEN_PREFIX),
+  })) {
+    if (!isTokenRecord(key, value)) continue;
+    recordsScanned += 1;
+
+    const timestamp = getTokenTimestamp(value);
+    if (timestamp === null || timestamp < args.sinceMs || timestamp > args.untilMs) {
+      continue;
+    }
+
+    addToAccumulator(totals, value);
+
+    const userId = normalizeText(value.userId);
+    const username = typeof value.username === "string" ? value.username : undefined;
+    const dialogId = normalizeText(value.dialogId);
+    const provider = normalizeText(value.provider);
+    const model = normalizeText(value.model);
+    const serviceTier =
+      typeof value.billing_service_tier === "string" && value.billing_service_tier.trim()
+        ? value.billing_service_tier.trim()
+        : undefined;
+    const agentKey = normalizeText(value.cybotId);
+
+    addGroupRecord(users, userId, value, { userId, username });
+    addGroupRecord(dialogs, `${userId}\u0000${dialogId}`, value, {
+      userId,
+      username,
+      dialogId,
+    });
+    addGroupRecord(models, `${provider}\u0000${model}\u0000${serviceTier ?? ""}`, value, {
+      provider,
+      model,
+      serviceTier,
+    });
+    addGroupRecord(agents, agentKey, value, { agentKey });
+  }
+
+  const totalCost = roundMetric(totals.cost);
+  const userLabelCache = new Map<string, Awaited<ReturnType<typeof readUserLabel>>>();
+  const getUserLabel = async (userId: string) => {
+    if (!userLabelCache.has(userId)) {
+      userLabelCache.set(userId, await readUserLabel(args.store, userId));
+    }
+    return userLabelCache.get(userId) ?? {};
+  };
+
+  return {
+    generatedAt: new Date(args.nowMs ?? Date.now()).toISOString(),
+    sinceMs: args.sinceMs,
+    untilMs: args.untilMs,
+    limit,
+    summary: {
+      ...metricFields(totals, totalCost),
+      recordsScanned,
+      recordsInWindow: totals.count,
+      totalCost,
+    },
+    rankings: {
+      users: await Promise.all(
+        sortedEntries(users, limit).map(async ([, acc]) => {
+          const userLabel = await getUserLabel(acc.userId);
+          return {
+            ...metricFields(acc, totalCost),
+            userId: acc.userId,
+            email: userLabel.email,
+            username: userLabel.username ?? acc.username,
+          };
+        })
+      ),
+      dialogs: await Promise.all(
+        sortedEntries(dialogs, limit).map(async ([, acc]) => {
+          const userLabel = await getUserLabel(acc.userId);
+          return {
+            ...metricFields(acc, totalCost),
+            userId: acc.userId,
+            username: userLabel.username ?? acc.username,
+            dialogId: acc.dialogId,
+            title: await readDialogTitle(args.store, acc.userId, acc.dialogId),
+          };
+        })
+      ),
+      models: sortedEntries(models, limit).map(([, acc]) => ({
+        ...metricFields(acc, totalCost),
+        provider: acc.provider,
+        model: acc.model,
+        serviceTier: acc.serviceTier,
+      })),
+      agents: await Promise.all(
+        sortedEntries(agents, limit).map(async ([, acc]) => ({
+          ...metricFields(acc, totalCost),
+          agentKey: acc.agentKey,
+          ...(await readAgentLabel(args.store, acc.agentKey)),
+        }))
+      ),
+    },
+  };
+}
+
+const parseMsParam = (value: string | null) => {
+  if (!value) return null;
+  const asNumber = Number(value);
+  if (Number.isFinite(asNumber)) return asNumber;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : null;
+};
+
+export async function handleAdminUsageReport(req: Request) {
+  if (req.method === "OPTIONS") {
+    return handleOptionsRequest();
+  }
+
+  const { userId: actionUserId } = req.user;
+  const permissionError = checkAdminPermission(actionUserId);
+  if (permissionError) return permissionError;
+
+  try {
+    const url = new URL(req.url);
+    const sinceMs = parseMsParam(url.searchParams.get("sinceMs"));
+    const untilMs = parseMsParam(url.searchParams.get("untilMs"));
+    const limit = Number(url.searchParams.get("limit") || "20");
+
+    if (sinceMs === null || untilMs === null || sinceMs > untilMs) {
+      return createErrorResponse("Invalid usage report time range", 400);
+    }
+
+    const report = await buildAdminUsageReport({
+      store: getServerAuthorityStore(),
+      sinceMs,
+      untilMs,
+      limit,
+    });
+
+    return createSuccessResponse(report);
+  } catch {
+    return createErrorResponse("Internal server error");
+  }
+}