@littlebearapps/platform-admin-sdk 1.4.2 → 2.0.0

package/templates/shared/workers/lib/usage/collectors/custom-http.ts

@@ -0,0 +1,151 @@
+/**
+ * Custom HTTP Collector Factory
+ *
+ * Factory function for creating collectors that fetch metrics from arbitrary
+ * REST APIs. Use when no dedicated collector exists for your provider.
+ *
+ * Supports bearer token, basic auth, and API key header authentication.
+ * Extracts multiple metrics from a single JSON response using dot-notation paths.
+ *
+ * @example
+ * ```ts
+ * import { createCustomCollector } from './custom-http';
+ *
+ * const myCollector = createCustomCollector({
+ *   name: 'my-api',
+ *   url: 'https://api.example.com/v1/usage',
+ *   auth: { type: 'bearer', envKey: 'MY_API_TOKEN' },
+ *   metrics: {
+ *     requests: { jsonPath: 'data.total_requests', unit: 'count' },
+ *     cost: { jsonPath: 'data.billing.amount', unit: 'usd', isCost: true },
+ *   },
+ * });
+ *
+ * // Register in COLLECTORS array:
+ * // const COLLECTORS = [myCollector];
+ * ```
+ */
+
+import type { Env, CustomHttpCollectorConfig } from '../shared';
+import { fetchWithRetry } from '../shared';
+import { createLoggerFromEnv } from '@littlebearapps/platform-consumer-sdk';
+import type { ExternalCollector } from './index';
+
+/** Extracted metrics result from a custom collector */
+export interface CustomMetrics {
+  /** Metric values keyed by name */
+  values: Record<string, number>;
+  /** Metadata about each metric */
+  meta: Record<string, { unit: string; isCost: boolean }>;
+  /** Source URL that was fetched */
+  source: string;
+}
+
+/**
+ * Extract a value from a nested object using dot-notation path.
+ * Returns undefined if the path doesn't exist.
+ */
+function extractJsonPath(obj: unknown, path: string): unknown {
+  const parts = path.split('.');
+  let current: unknown = obj;
+
+  for (const part of parts) {
+    if (current === null || current === undefined || typeof current !== 'object') {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[part];
+  }
+
+  return current;
+}
+
+/**
+ * Build request headers for the configured auth type.
+ */
+function buildAuthHeaders(
+  config: CustomHttpCollectorConfig,
+  env: Env
+): Record<string, string> | null {
+  const headers: Record<string, string> = { ...config.headers };
+
+  if (config.auth.type === 'bearer') {
+    const token = (env as Record<string, unknown>)[config.auth.envKey] as string | undefined;
+    if (!token) return null;
+    headers['Authorization'] = `Bearer ${token}`;
+  } else if (config.auth.type === 'basic') {
+    const username = (env as Record<string, unknown>)[config.auth.usernameEnvKey] as
+      | string
+      | undefined;
+    const password = (env as Record<string, unknown>)[config.auth.passwordEnvKey] as
+      | string
+      | undefined;
+    if (!username || !password) return null;
+    headers['Authorization'] = `Basic ${btoa(`${username}:${password}`)}`;
+  } else if (config.auth.type === 'api-key') {
+    const key = (env as Record<string, unknown>)[config.auth.envKey] as string | undefined;
+    if (!key) return null;
+    headers[config.auth.headerName] = key;
+  }
+
+  return headers;
+}
+
+/**
+ * Create a custom HTTP collector from a configuration object.
+ *
+ * The collector fetches the configured URL, parses the JSON response,
+ * and extracts metrics using the provided JSON paths.
+ */
+export function createCustomCollector(
+  config: CustomHttpCollectorConfig
+): ExternalCollector<CustomMetrics | null> {
+  return {
+    name: config.name,
+    defaultValue: null,
+    collect: async (env: Env): Promise<CustomMetrics | null> => {
+      const log = createLoggerFromEnv(env, 'platform-usage', `platform:usage:${config.name}`);
+
+      const headers = buildAuthHeaders(config, env);
+      if (!headers) {
+        log.info(`No credentials configured for ${config.name}, skipping collection`);
+        return null;
+      }
+
+      try {
+        const response = await fetchWithRetry(config.url, { headers });
+
+        if (!response.ok) {
+          const errorText = await response.text();
+          if (response.status === 401 || response.status === 403) {
+            log.info(`${config.name} API access denied`, { status: response.status });
+            return null;
+          }
+          log.error(`${config.name} API returned ${response.status}: ${errorText}`);
+          return null;
+        }
+
+        const data = (await response.json()) as unknown;
+
+        const values: Record<string, number> = {};
+        const meta: Record<string, { unit: string; isCost: boolean }> = {};
+
+        for (const [metricName, metricConfig] of Object.entries(config.metrics)) {
+          const raw = extractJsonPath(data, metricConfig.jsonPath);
+          const value = typeof raw === 'number' ? raw : parseFloat(String(raw || '0'));
+          values[metricName] = isNaN(value) ? 0 : value;
+          meta[metricName] = { unit: metricConfig.unit, isCost: metricConfig.isCost ?? false };
+        }
+
+        log.info(`Collected ${config.name} metrics`, {
+          metricCount: Object.keys(values).length,
+          values,
+        });
+
+        return { values, meta, source: config.url };
+      } catch (error) {
+        log.error(`Failed to collect ${config.name} metrics`, error);
+        return null;
+      }
+    },
+  };
+}

package/templates/shared/workers/lib/usage/collectors/deepseek.ts

@@ -0,0 +1,92 @@
+/**
+ * DeepSeek Balance Collector
+ *
+ * Collects account balance from the DeepSeek API.
+ * This is a STOCK metric (balance remaining), not a FLOW metric (usage).
+ * Do NOT sum these values in dashboards - display as a gauge/runway indicator.
+ *
+ * @see https://api-docs.deepseek.com/api/get-user-balance
+ */
+
+import type { Env, DeepSeekBalanceData } from '../shared';
+import { fetchWithRetry } from '../shared';
+import { createLoggerFromEnv } from '@littlebearapps/platform-consumer-sdk';
+import type { ExternalCollector } from './index';
+
+/**
+ * Collect DeepSeek account balance.
+ * Returns the current balance snapshot - this is NOT daily usage.
+ */
+export async function collectDeepSeekBalance(env: Env): Promise<DeepSeekBalanceData | null> {
+  const log = createLoggerFromEnv(env, 'platform-usage', 'platform:usage:deepseek');
+  if (!env.DEEPSEEK_API_KEY) {
+    log.info('No DEEPSEEK_API_KEY configured, skipping balance collection');
+    return null;
+  }
+
+  try {
+    const response = await fetchWithRetry('https://api.deepseek.com/user/balance', {
+      headers: {
+        Authorization: `Bearer ${env.DEEPSEEK_API_KEY}`,
+        'Content-Type': 'application/json',
+      },
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      if (response.status === 401 || response.status === 403) {
+        log.info('Balance API access denied - check API key permissions', {
+          status: response.status,
+        });
+        return null;
+      }
+      log.error(`Balance API returned ${response.status}: ${errorText}`);
+      return null;
+    }
+
+    const data = (await response.json()) as {
+      is_available?: boolean;
+      balance_infos?: Array<{
+        currency?: string;
+        total_balance?: string;
+        granted_balance?: string;
+        topped_up_balance?: string;
+      }>;
+    };
+
+    // Find USD balance (or first available)
+    const balanceInfo =
+      data.balance_infos?.find((b) => b.currency === 'USD') || data.balance_infos?.[0];
+
+    if (!balanceInfo) {
+      log.info('No balance info returned from API');
+      return null;
+    }
+
+    const result: DeepSeekBalanceData = {
+      totalBalance: parseFloat(balanceInfo.total_balance || '0'),
+      grantedBalance: parseFloat(balanceInfo.granted_balance || '0'),
+      toppedUpBalance: parseFloat(balanceInfo.topped_up_balance || '0'),
+      isAvailable: data.is_available ?? false,
+      currency: balanceInfo.currency || 'USD',
+    };
+
+    log.info('Collected DeepSeek balance', {
+      totalBalance: result.totalBalance,
+      currency: result.currency,
+      isAvailable: result.isAvailable,
+    });
+
+    return result;
+  } catch (error) {
+    log.error('Failed to collect DeepSeek balance', error);
+    return null;
+  }
+}
+
+/** Collector registration for use in collectors/index.ts COLLECTORS array */
+export const deepseekCollector: ExternalCollector<DeepSeekBalanceData | null> = {
+  name: 'deepseek',
+  collect: collectDeepSeekBalance,
+  defaultValue: null,
+};

package/templates/shared/workers/lib/usage/collectors/gemini.ts

@@ -0,0 +1,263 @@
+/**
+ * Google Gemini Usage Collector
+ *
+ * Collects API usage metrics from Google Cloud Monitoring API.
+ * This is a FLOW metric (actual usage) - safe to sum/aggregate.
+ *
+ * Authentication uses native Web Crypto API to sign JWTs for service account auth.
+ * Does NOT require googleapis or jsonwebtoken packages.
+ *
+ * Groups by API method (GenerateContent, EmbedContent, etc.) for breakdown.
+ * Includes cost estimation based on Gemini 2.0 Flash pricing.
+ *
+ * Advanced: Requires GCP service account with Cloud Monitoring read access.
+ *
+ * @see https://cloud.google.com/monitoring/api/ref_v3/rest/v3/projects.timeSeries/query
+ */
+
+import type { Env, GeminiUsageData } from '../shared';
+import { createLoggerFromEnv } from '@littlebearapps/platform-consumer-sdk';
+import type { ExternalCollector } from './index';
+
+/** Service account credentials structure (from GCP JSON key file) */
+interface ServiceAccountCredentials {
+  type: string;
+  project_id: string;
+  private_key_id: string;
+  private_key: string;
+  client_email: string;
+  client_id: string;
+  auth_uri: string;
+  token_uri: string;
+}
+
+/** Convert a PEM-encoded private key to a CryptoKey for signing. */
+async function importPrivateKey(pem: string): Promise<CryptoKey> {
+  const pemContents = pem
+    .replace(/-----BEGIN PRIVATE KEY-----/, '')
+    .replace(/-----END PRIVATE KEY-----/, '')
+    .replace(/\s/g, '');
+
+  const binaryString = atob(pemContents);
+  const bytes = new Uint8Array(binaryString.length);
+  for (let i = 0; i < binaryString.length; i++) {
+    bytes[i] = binaryString.charCodeAt(i);
+  }
+
+  return crypto.subtle.importKey(
+    'pkcs8',
+    bytes.buffer,
+    { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' },
+    false,
+    ['sign']
+  );
+}
+
+/** Base64URL encode (for JWT) */
+function base64UrlEncode(data: string | ArrayBuffer): string {
+  let base64: string;
+  if (typeof data === 'string') {
+    base64 = btoa(data);
+  } else {
+    const bytes = new Uint8Array(data);
+    let binary = '';
+    for (let i = 0; i < bytes.length; i++) {
+      binary += String.fromCharCode(bytes[i]);
+    }
+    base64 = btoa(binary);
+  }
+  return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+}
+
+/** Create a signed JWT for Google service account authentication. */
+async function createServiceAccountJwt(credentials: ServiceAccountCredentials): Promise<string> {
+  const now = Math.floor(Date.now() / 1000);
+
+  const header = { alg: 'RS256', typ: 'JWT' };
+  const payload = {
+    iss: credentials.client_email,
+    sub: credentials.client_email,
+    aud: 'https://oauth2.googleapis.com/token',
+    iat: now,
+    exp: now + 3600,
+    scope: 'https://www.googleapis.com/auth/monitoring.read',
+  };
+
+  const headerB64 = base64UrlEncode(JSON.stringify(header));
+  const payloadB64 = base64UrlEncode(JSON.stringify(payload));
+  const unsignedToken = `${headerB64}.${payloadB64}`;
+
+  const privateKey = await importPrivateKey(credentials.private_key);
+  const encoder = new TextEncoder();
+  const signature = await crypto.subtle.sign(
+    'RSASSA-PKCS1-v1_5',
+    privateKey,
+    encoder.encode(unsignedToken)
+  );
+
+  return `${unsignedToken}.${base64UrlEncode(signature)}`;
+}
+
+/** Exchange JWT for an access token from Google OAuth2. */
+async function getAccessToken(credentials: ServiceAccountCredentials): Promise<string | null> {
+  try {
+    const jwt = await createServiceAccountJwt(credentials);
+
+    const response = await fetch('https://oauth2.googleapis.com/token', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
+        assertion: jwt,
+      }),
+    });
+
+    if (!response.ok) {
+      return null;
+    }
+
+    const data = (await response.json()) as { access_token?: string };
+    return data.access_token || null;
+  } catch {
+    return null;
+  }
+}
+
+// Gemini 2.0 Flash pricing: ~$0.075 per 1K requests (rough average)
+const GEMINI_COST_PER_1K_REQUESTS = 0.075;
+
+/**
+ * Collect Google Gemini API usage from Cloud Monitoring.
+ * Returns request counts grouped by API method for the last 24 hours.
+ */
+export async function collectGeminiUsage(env: Env): Promise<GeminiUsageData | null> {
+  const log = createLoggerFromEnv(env, 'platform-usage', 'platform:usage:gemini');
+
+  if (!env.GCP_PROJECT_ID || !env.GCP_SERVICE_ACCOUNT_JSON) {
+    log.info('No GCP credentials configured, skipping Gemini usage collection');
+    return null;
+  }
+
+  let credentials: ServiceAccountCredentials;
+  try {
+    credentials = JSON.parse(env.GCP_SERVICE_ACCOUNT_JSON) as ServiceAccountCredentials;
+  } catch (error) {
+    log.error('Failed to parse GCP_SERVICE_ACCOUNT_JSON', error);
+    return null;
+  }
+
+  try {
+    const accessToken = await getAccessToken(credentials);
+    if (!accessToken) {
+      log.error('Failed to obtain Google Cloud access token');
+      return null;
+    }
+
+    const now = new Date();
+    const yesterday = new Date(now.getTime() - 24 * 60 * 60 * 1000);
+
+    // MQL query for generativelanguage.googleapis.com request counts
+    const mqlQuery = `
+      fetch consumed_api
+      | metric 'serviceruntime.googleapis.com/api/request_count'
+      | filter resource.service == 'generativelanguage.googleapis.com'
+      | group_by [resource.method]
+      | align rate(1d)
+      | every 1d
+    `.trim();
+
+    const response = await fetch(
+      `https://monitoring.googleapis.com/v3/projects/${env.GCP_PROJECT_ID}/timeSeries:query`,
+      {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ query: mqlQuery }),
+      }
+    );
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      if (response.status === 401 || response.status === 403) {
+        log.info('Cloud Monitoring API access denied - check service account permissions', {
+          status: response.status,
+        });
+        return null;
+      }
+      log.error(`Cloud Monitoring API returned ${response.status}: ${errorText}`);
+      return null;
+    }
+
+    const data = (await response.json()) as {
+      timeSeriesData?: Array<{
+        labelValues?: Array<{ stringValue?: string }>;
+        pointData?: Array<{
+          values?: Array<{ doubleValue?: number; int64Value?: string }>;
+          timeInterval?: { startTime?: string; endTime?: string };
+        }>;
+      }>;
+    };
+
+    let requestCount = 0;
+    let periodStart = yesterday.toISOString();
+    let periodEnd = now.toISOString();
+    const methodBreakdown: Record<string, number> = {};
+
+    if (data.timeSeriesData) {
+      for (const ts of data.timeSeriesData) {
+        const method = ts.labelValues?.[0]?.stringValue || 'unknown';
+        let methodCount = 0;
+
+        if (ts.pointData) {
+          for (const point of ts.pointData) {
+            if (point.values?.[0]) {
+              const value = point.values[0];
+              const count = value.doubleValue || parseInt(value.int64Value || '0', 10);
+              requestCount += count;
+              methodCount += count;
+            }
+            if (point.timeInterval) {
+              periodStart = point.timeInterval.startTime || periodStart;
+              periodEnd = point.timeInterval.endTime || periodEnd;
+            }
+          }
+        }
+
+        if (methodCount > 0) {
+          methodBreakdown[method] = (methodBreakdown[method] || 0) + methodCount;
+        }
+      }
+    }
+
+    const estimatedCostUsd = (requestCount / 1000) * GEMINI_COST_PER_1K_REQUESTS;
+
+    const result: GeminiUsageData = {
+      requestCount,
+      avgLatencyMs: 0, // Would need separate query for latency metrics
+      estimatedCostUsd,
+      periodStart,
+      periodEnd,
+      methodBreakdown,
+    };
+
+    log.info('Collected Gemini usage', {
+      requestCount: result.requestCount,
+      estimatedCostUsd: result.estimatedCostUsd,
+      methods: Object.keys(methodBreakdown).length,
+    });
+
+    return result;
+  } catch (error) {
+    log.error('Failed to collect Gemini usage', error);
+    return null;
+  }
+}
+
+/** Collector registration for use in collectors/index.ts COLLECTORS array */
+export const geminiCollector: ExternalCollector<GeminiUsageData | null> = {
+  name: 'gemini',
+  collect: collectGeminiUsage,
+  defaultValue: null,
+};