@littlebearapps/platform-admin-sdk 1.4.2 → 1.5.0

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

@@ -0,0 +1,362 @@
+/**
+ * GitHub Billing & Enterprise Collectors
+ *
+ * Collects billing data from GitHub APIs:
+ * - Organization billing usage (Actions, GHEC, GHAS, Packages, LFS, Copilot)
+ * - Enterprise consumed licenses (seat tracking) — optional
+ *
+ * Requires:
+ * - GITHUB_TOKEN: PAT with admin:org or read:org scope for org billing
+ * - GITHUB_ORG: Your GitHub organization slug
+ * - GITHUB_PAT: PAT with read:enterprise scope for enterprise licenses (optional)
+ * - GITHUB_ENTERPRISE_SLUG: Enterprise slug for license queries (optional)
+ *
+ * This is a FLOW metric (billing accumulates) - safe to SUM.
+ *
+ * @see https://docs.github.com/en/rest/billing
+ */
+
+import type {
+  Env,
+  GitHubBillingData,
+  GitHubPlanInfo,
+  GitHubUsageItem,
+  GitHubPlanInclusions,
+} from '../shared';
+import { fetchWithRetry } from '../shared';
+import { createLoggerFromEnv } from '@littlebearapps/platform-consumer-sdk';
+import type { ExternalCollector } from './index';
+
+/**
+ * Enterprise consumed licenses data.
+ */
+export interface GitHubEnterpriseSeats {
+  totalSeatsConsumed: number;
+  totalSeatsPurchased: number;
+  licenseBreakdown: {
+    visualStudio: number;
+    enterprise: number;
+    unlicensed: number;
+  };
+}
+
+/**
+ * Combined external metrics result for GitHub.
+ */
+export interface GitHubExternalMetrics {
+  billing: GitHubBillingData | null;
+  enterpriseSeats: GitHubEnterpriseSeats | null;
+}
+
+/**
+ * Get GitHub plan inclusions based on plan name.
+ * @see https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-actions/about-billing-for-github-actions
+ */
+export function getGitHubPlanInclusions(planName: string): GitHubPlanInclusions {
+  const lowerPlan = planName.toLowerCase();
+
+  if (lowerPlan.includes('enterprise')) {
+    return {
+      actionsMinutesIncluded: 50000,
+      actionsStorageGbIncluded: 50,
+      packagesStorageGbIncluded: 50,
+      codespacesHoursIncluded: 0,
+    };
+  }
+
+  if (lowerPlan.includes('team')) {
+    return {
+      actionsMinutesIncluded: 3000,
+      actionsStorageGbIncluded: 2,
+      packagesStorageGbIncluded: 2,
+      codespacesHoursIncluded: 0,
+    };
+  }
+
+  if (lowerPlan.includes('pro')) {
+    return {
+      actionsMinutesIncluded: 3000,
+      actionsStorageGbIncluded: 2,
+      packagesStorageGbIncluded: 2,
+      codespacesHoursIncluded: 180,
+    };
+  }
+
+  // GitHub Free (default)
+  return {
+    actionsMinutesIncluded: 2000,
+    actionsStorageGbIncluded: 0.5,
+    packagesStorageGbIncluded: 0.5,
+    codespacesHoursIncluded: 120,
+  };
+}
+
+/**
+ * Collect GitHub billing data using the usage API and org plan info.
+ * Requires GITHUB_ORG to be set (your GitHub organization slug).
+ */
+export async function collectGitHubBilling(env: Env): Promise<GitHubBillingData | null> {
+  const log = createLoggerFromEnv(env, 'platform-usage', 'platform:usage:github-billing');
+  if (!env.GITHUB_TOKEN) {
+    log.info('No GITHUB_TOKEN configured, skipping billing collection');
+    return null;
+  }
+  if (!env.GITHUB_ORG) {
+    log.info('No GITHUB_ORG configured, skipping billing collection');
+    return null;
+  }
+
+  const org = env.GITHUB_ORG;
+
+  try {
+    const headers = {
+      Authorization: `Bearer ${env.GITHUB_TOKEN}`,
+      Accept: 'application/vnd.github+json',
+      'X-GitHub-Api-Version': '2022-11-28',
+      'User-Agent': 'platform-usage-worker/1.0',
+    };
+
+    // Verify token scopes
+    const scopeCheck = await fetchWithRetry('https://api.github.com/user', { headers });
+    const scopes = scopeCheck.headers.get('X-OAuth-Scopes') || '';
+    if (scopes && !scopes.includes('admin:org') && !scopes.includes('read:org')) {
+      log.warn('Token may lack admin:org or read:org scope for billing access');
+    }
+
+    // Fetch org plan info
+    const orgResponse = await fetchWithRetry(`https://api.github.com/orgs/${org}`, { headers });
+    let planInfo: GitHubPlanInfo = {
+      planName: 'unknown',
+      filledSeats: 0,
+      totalSeats: 0,
+      privateRepos: 0,
+    };
+
+    if (orgResponse.ok) {
+      const orgData = (await orgResponse.json()) as {
+        plan?: { name: string; filled_seats: number; seats: number; private_repos: number };
+      };
+      if (orgData.plan) {
+        planInfo = {
+          planName: orgData.plan.name,
+          filledSeats: orgData.plan.filled_seats || 0,
+          totalSeats: orgData.plan.seats || 0,
+          privateRepos: orgData.plan.private_repos || 0,
+        };
+      }
+    } else {
+      log.warn('Could not fetch org info', { status: orgResponse.status });
+    }
+
+    // Fetch billing usage
+    const response = await fetchWithRetry(
+      `https://api.github.com/orgs/${org}/settings/billing/usage`,
+      { headers }
+    );
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      log.error(`Billing API returned ${response.status}: ${errorText}`);
+      return null;
+    }
+
+    const data = (await response.json()) as { usageItems: GitHubUsageItem[] };
+
+    if (!data.usageItems || !Array.isArray(data.usageItems)) {
+      log.error('Invalid response format - no usageItems array');
+      return null;
+    }
+
+    // Aggregate usage by product/SKU
+    const result: GitHubBillingData = {
+      plan: planInfo,
+      actionsMinutes: 0,
+      actionsMinutesCost: 0,
+      actionsStorageGbHours: 0,
+      actionsStorageCost: 0,
+      ghecUserMonths: 0,
+      ghecCost: 0,
+      ghasCodeSecurityUserMonths: 0,
+      ghasCodeSecurityCost: 0,
+      ghasSecretProtectionUserMonths: 0,
+      ghasSecretProtectionCost: 0,
+      packagesStorageGb: 0,
+      packagesStorageCost: 0,
+      packagesBandwidthGb: 0,
+      packagesBandwidthCost: 0,
+      lfsStorageGb: 0,
+      lfsStorageCost: 0,
+      lfsBandwidthGb: 0,
+      lfsBandwidthCost: 0,
+      copilotSeats: 0,
+      copilotCost: 0,
+      totalNetCost: 0,
+    };
+
+    for (const item of data.usageItems) {
+      result.totalNetCost += item.netAmount;
+
+      if (item.product === 'actions') {
+        if (
+          item.sku === 'Actions Linux' ||
+          item.sku === 'Actions macOS' ||
+          item.sku === 'Actions Windows'
+        ) {
+          result.actionsMinutes += item.quantity;
+          result.actionsMinutesCost += item.netAmount;
+        } else if (item.sku === 'Actions storage') {
+          result.actionsStorageGbHours += item.quantity;
+          result.actionsStorageCost += item.netAmount;
+        }
+      } else if (item.product === 'ghec') {
+        result.ghecUserMonths += item.quantity;
+        result.ghecCost += item.netAmount;
+      } else if (item.product === 'ghas') {
+        if (item.sku === 'Code Security') {
+          result.ghasCodeSecurityUserMonths += item.quantity;
+          result.ghasCodeSecurityCost += item.netAmount;
+        } else if (item.sku === 'Secret Protection') {
+          result.ghasSecretProtectionUserMonths += item.quantity;
+          result.ghasSecretProtectionCost += item.netAmount;
+        }
+      } else if (item.product === 'packages') {
+        if (item.unitType === 'gb' || item.sku?.toLowerCase().includes('storage')) {
+          result.packagesStorageGb += item.quantity;
+          result.packagesStorageCost += item.netAmount;
+        } else {
+          result.packagesBandwidthGb += item.quantity;
+          result.packagesBandwidthCost += item.netAmount;
+        }
+      } else if (item.product === 'git_lfs') {
+        if (item.sku?.toLowerCase().includes('storage')) {
+          result.lfsStorageGb += item.quantity;
+          result.lfsStorageCost += item.netAmount;
+        } else {
+          result.lfsBandwidthGb += item.quantity;
+          result.lfsBandwidthCost += item.netAmount;
+        }
+      } else if (item.product === 'copilot') {
+        result.copilotSeats += item.quantity;
+        result.copilotCost += item.netAmount;
+      }
+    }
+
+    log.info('Collected billing', {
+      actionsMinutes: result.actionsMinutes,
+      ghecUserMonths: result.ghecUserMonths,
+      totalNetCost: result.totalNetCost,
+    });
+
+    return result;
+  } catch (error) {
+    log.error('Failed to collect billing', error);
+    return null;
+  }
+}
+
+/**
+ * Collect GitHub Enterprise consumed licenses.
+ * Requires read:enterprise scope and GITHUB_ENTERPRISE_SLUG.
+ */
+export async function collectGitHubEnterpriseSeats(
+  env: Env
+): Promise<GitHubEnterpriseSeats | null> {
+  const log = createLoggerFromEnv(env, 'platform-usage', 'platform:usage:github-enterprise');
+
+  const token = env.GITHUB_PAT || env.GITHUB_TOKEN;
+  const enterpriseSlug = env.GITHUB_ENTERPRISE_SLUG;
+
+  if (!token) {
+    log.info('No GitHub token configured, skipping enterprise seat collection');
+    return null;
+  }
+
+  if (!enterpriseSlug) {
+    log.info('No GITHUB_ENTERPRISE_SLUG configured, skipping enterprise seat collection');
+    return null;
+  }
+
+  try {
+    const headers = {
+      Authorization: `Bearer ${token}`,
+      Accept: 'application/vnd.github+json',
+      'X-GitHub-Api-Version': '2022-11-28',
+      'User-Agent': 'platform-usage-worker/1.0',
+    };
+
+    const response = await fetchWithRetry(
+      `https://api.github.com/enterprises/${enterpriseSlug}/consumed-licenses`,
+      { headers }
+    );
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      if (response.status === 404) {
+        log.info('Enterprise not found or no access', { enterpriseSlug });
+        return null;
+      }
+      if (response.status === 403) {
+        log.warn('Token lacks read:enterprise scope for consumed-licenses API');
+        return null;
+      }
+      log.error(`Enterprise API returned ${response.status}: ${errorText}`);
+      return null;
+    }
+
+    const data = (await response.json()) as {
+      total_seats_consumed?: number;
+      total_seats_purchased?: number;
+      users?: Array<{
+        visual_studio_subscription_user?: boolean;
+        license_type?: string;
+      }>;
+    };
+
+    const result: GitHubEnterpriseSeats = {
+      totalSeatsConsumed: data.total_seats_consumed || 0,
+      totalSeatsPurchased: data.total_seats_purchased || 0,
+      licenseBreakdown: { visualStudio: 0, enterprise: 0, unlicensed: 0 },
+    };
+
+    if (data.users && Array.isArray(data.users)) {
+      for (const user of data.users) {
+        if (user.visual_studio_subscription_user) {
+          result.licenseBreakdown.visualStudio++;
+        } else if (user.license_type === 'Enterprise') {
+          result.licenseBreakdown.enterprise++;
+        } else {
+          result.licenseBreakdown.unlicensed++;
+        }
+      }
+    }
+
+    log.info('Collected enterprise seats', {
+      consumed: result.totalSeatsConsumed,
+      purchased: result.totalSeatsPurchased,
+    });
+
+    return result;
+  } catch (error) {
+    log.error('Failed to collect enterprise seats', error);
+    return null;
+  }
+}
+
+/**
+ * Collect all GitHub external metrics (billing + enterprise seats).
+ */
+export async function collectGitHubMetrics(env: Env): Promise<GitHubExternalMetrics> {
+  const [billing, enterpriseSeats] = await Promise.all([
+    collectGitHubBilling(env),
+    collectGitHubEnterpriseSeats(env),
+  ]);
+
+  return { billing, enterpriseSeats };
+}
+
+/** Collector registration for use in collectors/index.ts COLLECTORS array */
+export const githubCollector: ExternalCollector<GitHubExternalMetrics> = {
+  name: 'github',
+  collect: collectGitHubMetrics,
+  defaultValue: { billing: null, enterpriseSeats: null },
+};

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

@@ -4,16 +4,15 @@
  * Framework for collecting billing and usage data from external providers.
  * Each collector handles errors gracefully - one failure doesn't stop others.
  *
- * TODO: Add collectors for your external providers. See example.ts for a
- * collector template. Common providers include:
- * - GitHub: Org billing + Enterprise consumed licenses
- * - OpenAI: Organization usage (Admin API)
- * - Anthropic: Organization usage (Admin API)
- * - Stripe: Revenue and subscription data
+ * 10 built-in collectors are available. Uncomment the imports for providers
+ * you use, then add them to the COLLECTORS array below.
  *
  * Metric types:
  * - FLOW metrics: Usage that accumulates (requests, tokens) - safe to SUM
  * - STOCK metrics: Point-in-time values (balance, quota) - do NOT SUM
+ *
+ * See example.ts for a collector template or custom-http.ts for a factory
+ * that creates collectors from config objects.
  */
 
 import type { Env } from '../shared';
@@ -39,8 +38,6 @@ export interface ExternalCollector<T> {
 
 /**
  * Combined external metrics from all providers.
- *
- * TODO: Add your provider result types here.
  */
 export interface ExternalMetrics {
   /** Results keyed by collector name */
@@ -58,18 +55,37 @@ export interface ExternalMetrics {
 /**
  * Register your collectors here.
  *
- * TODO: Import and add your collector modules. Example:
+ * Uncomment the imports for the providers you use, then add them to the
+ * COLLECTORS array. Each collector checks for its API key at runtime and
+ * returns null if not configured — safe to register even if unused.
  *
- *   import { githubCollector } from './github';
+ * FLOW metrics (usage — safe to SUM):
  *   import { openaiCollector } from './openai';
+ *   import { anthropicCollector } from './anthropic';
+ *   import { githubCollector } from './github';
+ *   import { stripeCollector } from './stripe';
+ *   import { apifyCollector } from './apify';
+ *   import { resendCollector } from './resend';
+ *   import { geminiCollector } from './gemini';
+ *
+ * STOCK metrics (gauge — do NOT SUM):
+ *   import { deepseekCollector } from './deepseek';
+ *   import { minimaxCollector } from './minimax';
  *
- *   const COLLECTORS: ExternalCollector<unknown>[] = [
- *     githubCollector,
- *     openaiCollector,
- *   ];
+ * Custom REST API (factory):
+ *   import { createCustomCollector } from './custom-http';
  */
 const COLLECTORS: ExternalCollector<unknown>[] = [
-  // Add your collectors here
+  // Uncomment the collectors you need:
+  // openaiCollector,
+  // anthropicCollector,
+  // githubCollector,
+  // stripeCollector,
+  // apifyCollector,
+  // resendCollector,
+  // deepseekCollector,
+  // minimaxCollector,
+  // geminiCollector,
 ];
 
 // =============================================================================

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

@@ -0,0 +1,106 @@
+/**
+ * Minimax Quota Collector
+ *
+ * Collects remaining quota from the Minimax API.
+ * This is a STOCK metric (quota remaining), not a FLOW metric (usage).
+ * Do NOT sum these values in dashboards - display as a gauge/runway indicator.
+ *
+ * Note: The exact API endpoint may need adjustment based on Minimax documentation.
+ * The coding_plan endpoint provides quota information for coding/API usage.
+ */
+
+import type { Env, MinimaxQuotaData } from '../shared';
+import { fetchWithRetry } from '../shared';
+import { createLoggerFromEnv } from '@littlebearapps/platform-consumer-sdk';
+import type { ExternalCollector } from './index';
+
+/**
+ * Collect Minimax remaining quota.
+ * Returns the current quota snapshot - this is NOT daily usage.
+ */
+export async function collectMinimaxQuota(env: Env): Promise<MinimaxQuotaData | null> {
+  const log = createLoggerFromEnv(env, 'platform-usage', 'platform:usage:minimax');
+  if (!env.MINIMAX_API_KEY) {
+    log.info('No MINIMAX_API_KEY configured, skipping quota collection');
+    return null;
+  }
+
+  try {
+    const response = await fetchWithRetry('https://api.minimax.chat/v1/user/coding_plan', {
+      headers: {
+        Authorization: `Bearer ${env.MINIMAX_API_KEY}`,
+        'Content-Type': 'application/json',
+      },
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      if (response.status === 401 || response.status === 403) {
+        log.info('Quota API access denied - check API key permissions', {
+          status: response.status,
+        });
+        return null;
+      }
+      if (response.status === 404) {
+        log.info('Minimax quota endpoint not found - may need API endpoint update', {
+          status: response.status,
+        });
+        return null;
+      }
+      log.error(`Quota API returned ${response.status}: ${errorText}`);
+      return null;
+    }
+
+    const data = (await response.json()) as {
+      quota?: number;
+      total_quota?: number;
+      rest_quota?: number;
+      used_quota?: number;
+      plan_type?: string;
+      remaining_prompts?: number;
+      total_prompts?: number;
+    };
+
+    // Handle different possible response formats
+    let remainingQuota = 0;
+    let totalQuota = 0;
+
+    if (typeof data.rest_quota === 'number') {
+      remainingQuota = data.rest_quota;
+      totalQuota = data.total_quota || data.rest_quota + (data.used_quota || 0);
+    } else if (typeof data.remaining_prompts === 'number') {
+      remainingQuota = data.remaining_prompts;
+      totalQuota = data.total_prompts || data.remaining_prompts;
+    } else if (typeof data.quota === 'number') {
+      remainingQuota = data.quota;
+      totalQuota = data.total_quota || data.quota;
+    }
+
+    const usagePercentage = totalQuota > 0 ? ((totalQuota - remainingQuota) / totalQuota) * 100 : 0;
+
+    const result: MinimaxQuotaData = {
+      remainingQuota,
+      totalQuota,
+      usagePercentage,
+      planType: data.plan_type || 'coding_plan',
+    };
+
+    log.info('Collected Minimax quota', {
+      remainingQuota: result.remainingQuota,
+      totalQuota: result.totalQuota,
+      usagePercentage: result.usagePercentage.toFixed(1),
+    });
+
+    return result;
+  } catch (error) {
+    log.error('Failed to collect Minimax quota', error);
+    return null;
+  }
+}
+
+/** Collector registration for use in collectors/index.ts COLLECTORS array */
+export const minimaxCollector: ExternalCollector<MinimaxQuotaData | null> = {
+  name: 'minimax',
+  collect: collectMinimaxQuota,
+  defaultValue: null,
+};