@littlebearapps/platform-admin-sdk 2.0.0 → 2.1.0

package/templates/full/dashboard/src/lib/usage/allowance-config.ts.hbs

@@ -0,0 +1,547 @@
+/**
+ * Cloudflare Allowance & Licensing Configuration
+ *
+ * Defines monthly limits for Cloudflare services to track "Usage vs. Included Thresholds".
+ * These values represent the Workers Paid plan allowances and free tier limits.
+ *
+ * @see https://developers.cloudflare.com/workers/platform/pricing/
+ */
+
+/**
+ * Service type identifiers
+ */
+export type ServiceType =
+  | 'workers'
+  | 'd1'
+  | 'kv'
+  | 'r2'
+  | 'durableObjects'
+  | 'vectorize'
+  | 'aiGateway'
+  | 'workersAI'
+  | 'pages'
+  | 'queues';
+
+/**
+ * Utilization status based on percentage thresholds
+ */
+export type UtilizationStatus = 'green' | 'yellow' | 'red';
+
+/**
+ * Service allowance definition
+ */
+export interface ServiceAllowance {
+  /** Human-readable service name */
+  name: string;
+  /** Monthly allowance value (in native units) */
+  monthlyLimit: number;
+  /** Unit of measurement */
+  unit: string;
+  /** Whether this is a paid plan limit (vs free tier) */
+  isPaidPlan: boolean;
+  /** Description of the allowance */
+  description: string;
+}
+
+/**
+ * Project-specific allowance overrides
+ */
+export interface ProjectAllowance {
+  projectId: string;
+  projectName: string;
+  /** Primary resource type for this project (e.g., D1 writes for database-heavy projects) */
+  primaryResource: ServiceType;
+  /** Custom limits that override account-level defaults */
+  overrides?: Partial<Record<ServiceType, number>>;
+}
+
+/**
+ * Account-level Cloudflare service allowances (Workers Paid Plan)
+ *
+ * Based on Cloudflare pricing as of January 2026:
+ * - Workers Paid: $5/month includes 10M requests
+ * - D1: 50M writes/month for paid accounts
+ * - R2: 10 GB Class A operations included
+ */
+export const CF_ALLOWANCES: Record<ServiceType, ServiceAllowance> = {
+  workers: {
+    name: 'Workers Requests',
+    monthlyLimit: 10_000_000, // 10M requests/month included
+    unit: 'requests',
+    isPaidPlan: true,
+    description: '10M requests included with Workers Paid ($5/mo)',
+  },
+  d1: {
+    name: 'D1 Writes',
+    monthlyLimit: 50_000_000, // 50M writes/month threshold (primary metric for utilization)
+    unit: 'rows written',
+    isPaidPlan: true,
+    description: '25B rows read + 50M rows written per month included',
+  },
+  kv: {
+    name: 'KV Writes',
+    monthlyLimit: 1_000_000, // 1M writes/month threshold (primary metric for utilization)
+    unit: 'writes',
+    isPaidPlan: true,
+    description: '10M reads + 1M writes/deletes/lists per month included',
+  },
+  r2: {
+    name: 'R2 Storage',
+    monthlyLimit: 10_000_000_000, // 10GB storage (primary metric for utilization)
+    unit: 'bytes',
+    isPaidPlan: true,
+    description: '10GB storage + 1M Class A + 10M Class B ops per month included',
+  },
+  durableObjects: {
+    name: 'Durable Objects Requests',
+    monthlyLimit: 1_000_000, // 1M requests/month Workers Paid Plan
+    unit: 'requests',
+    isPaidPlan: true,
+    description: '1M requests included in Workers Paid Plan',
+  },
+  vectorize: {
+    name: 'Vectorize Stored Dimensions',
+    monthlyLimit: 10_000_000, // 10M stored dimensions/month Workers Paid Plan
+    unit: 'dimensions',
+    isPaidPlan: true,
+    description:
+      '10M stored dimensions + 50M queried dimensions per month included in Workers Paid Plan',
+  },
+  aiGateway: {
+    name: 'AI Gateway Requests',
+    monthlyLimit: Infinity, // Unlimited (free service)
+    unit: 'requests',
+    isPaidPlan: false,
+    description: 'AI Gateway is free (cost is from underlying AI provider)',
+  },
+  // CONSERVATIVE: Set to 0 allowance for accurate billing visibility on Workers Paid Plan.
+  // Cloudflare provides a 10K neurons/day free tier (resets daily at midnight UTC),
+  // but we report from first neuron to ensure costs are never hidden.
+  // Better to over-report than under-report for budget tracking.
+  workersAI: {
+    name: 'Workers AI Neurons',
+    monthlyLimit: 0, // Pay-as-you-go from first neuron on Workers Paid
+    unit: 'neurons',
+    isPaidPlan: true,
+    description:
+      'Pay-as-you-go: $0.011/1K neurons. No paid plan inclusion (free tier may apply but not tracked).',
+  },
+  pages: {
+    name: 'Pages Builds',
+    monthlyLimit: 500, // 500 builds/month free
+    unit: 'builds',
+    isPaidPlan: false,
+    description: '500 builds per month in free tier',
+  },
+  queues: {
+    name: 'Queues Messages',
+    monthlyLimit: 1_000_000, // 1M messages/month free
+    unit: 'messages',
+    isPaidPlan: false,
+    description: '1M messages per month in free tier',
+  },
+};
+
+/**
+ * Daily limits (derived from monthly for rate limiting purposes)
+ *
+ * IMPORTANT: Most services reset MONTHLY, so daily limit = monthly / 30.
+ * Services with 0 monthly allowance (pay-as-you-go) have 0 daily limit.
+ */
+export const CF_DAILY_LIMITS: Record<ServiceType, number> = {
+  workers: Math.floor(CF_ALLOWANCES.workers.monthlyLimit / 30), // ~333K/day
+  d1: Math.floor(CF_ALLOWANCES.d1.monthlyLimit / 30), // ~1.67M/day
+  kv: Math.floor(CF_ALLOWANCES.kv.monthlyLimit / 30), // ~33K/day
+  r2: Math.floor(CF_ALLOWANCES.r2.monthlyLimit / 30),
+  durableObjects: Math.floor(CF_ALLOWANCES.durableObjects.monthlyLimit / 30),
+  vectorize: 0, // Pay-as-you-go (no free tier tracked)
+  aiGateway: Infinity,
+  workersAI: 0, // Pay-as-you-go (no free tier tracked)
+  pages: Math.floor(CF_ALLOWANCES.pages.monthlyLimit / 30),
+  queues: Math.floor(CF_ALLOWANCES.queues.monthlyLimit / 30),
+};
+
+/**
+ * Project-specific configurations with primary resource assignments
+ *
+ * NOTE: Project overrides removed (2026-01-15). Utilization now calculated
+ * against account-level CF_ALLOWANCES to match actual Cloudflare billing.
+ * If project-level budgets are needed in future, implement via D1 usage_settings
+ * table with UI configuration in ThresholdSettings.
+ */
+export const PROJECT_ALLOWANCES: ProjectAllowance[] = [
+  {
+    projectId: '{{projectSlug}}',
+    projectName: '{{projectName}}',
+    primaryResource: 'd1',
+    // Utilization uses CF_ALLOWANCES.d1 (50M writes/month)
+  },
+  {
+    projectId: 'platform',
+    projectName: 'Platform',
+    primaryResource: 'd1',
+    // Utilization uses CF_ALLOWANCES.d1 (50M writes/month)
+  },
+];
+
+/**
+ * Utilization threshold percentages for traffic light status
+ */
+export const UTILIZATION_THRESHOLDS = {
+  /** Green zone: < 70% utilization */
+  green: 70,
+  /** Yellow zone: 70-90% utilization */
+  yellow: 90,
+  /** Red zone: > 90% utilization (or overage) */
+  red: 100,
+} as const;
+
+/**
+ * Project data from D1 registry (via /api/usage/projects)
+ */
+interface D1Project {
+  projectId: string;
+  displayName: string;
+  primaryResource: string | null;
+  customLimit: number | null;
+  status: string;
+}
+
+/**
+ * Map D1 resource type to ServiceType
+ */
+function mapResourceType(d1Resource: string | null): ServiceType {
+  if (!d1Resource) return 'workers';
+
+  const mapping: Record<string, ServiceType> = {
+    worker: 'workers',
+    workers: 'workers',
+    d1: 'd1',
+    kv: 'kv',
+    r2: 'r2',
+    vectorize: 'vectorize',
+    ai_gateway: 'aiGateway',
+    workers_ai: 'workersAI',
+    workersai: 'workersAI',
+    pages: 'pages',
+    queue: 'queues',
+    durable_object: 'durableObjects',
+  };
+
+  return mapping[d1Resource.toLowerCase()] ?? 'workers';
+}
+
+/**
+ * Fetch project allowances from D1 registry via API.
+ * Falls back to static PROJECT_ALLOWANCES if the API fails.
+ *
+ * @param baseUrl - Base URL for the API
+ * @param fetchFn - Optional fetch function (for SSR environments)
+ * @returns ProjectAllowance array
+ */
+export async function fetchProjectAllowances(
+  baseUrl: string = '',
+  fetchFn: typeof fetch = fetch
+): Promise<ProjectAllowance[]> {
+  try {
+    const response = await fetchFn(`${baseUrl}/api/usage/projects`, {
+      credentials: 'include',
+      headers: {
+        Accept: 'application/json',
+      },
+    });
+
+    if (!response.ok) {
+      console.warn(`[allowance-config] API returned ${response.status}, using static fallback`);
+      return PROJECT_ALLOWANCES;
+    }
+
+    const json = (await response.json()) as {
+      success: boolean;
+      projects?: D1Project[];
+    };
+
+    if (!json.success || !json.projects) {
+      console.warn('[allowance-config] Invalid API response, using static fallback');
+      return PROJECT_ALLOWANCES;
+    }
+
+    // Convert D1 projects to ProjectAllowance format
+    const dynamicAllowances: ProjectAllowance[] = json.projects
+      .filter((p) => p.status === 'active' && p.primaryResource)
+      .map((p) => {
+        const primaryResource = mapResourceType(p.primaryResource);
+        const allowance: ProjectAllowance = {
+          projectId: p.projectId,
+          projectName: p.displayName,
+          primaryResource,
+        };
+
+        // Add custom limit as override if specified
+        if (p.customLimit && p.customLimit > 0) {
+          allowance.overrides = {
+            [primaryResource]: p.customLimit,
+          };
+        }
+
+        return allowance;
+      });
+
+    // If we got valid data, return it; otherwise fall back
+    if (dynamicAllowances.length > 0) {
+      console.log(
+        `[allowance-config] Loaded ${dynamicAllowances.length} projects from D1 registry`
+      );
+      return dynamicAllowances;
+    }
+
+    return PROJECT_ALLOWANCES;
+  } catch (error) {
+    console.warn('[allowance-config] Failed to fetch from API, using static fallback:', error);
+    return PROJECT_ALLOWANCES;
+  }
+}
+
+/**
+ * Get project allowances (sync version, returns static config)
+ * Use fetchProjectAllowances() for dynamic D1-backed data.
+ */
+export function getStaticProjectAllowances(): ProjectAllowance[] {
+  return PROJECT_ALLOWANCES;
+}
+
+/**
+ * Calculate utilization percentage
+ */
+export function calculateUtilizationPct(current: number, limit: number): number {
+  if (limit === Infinity || limit === 0) return 0;
+  return Math.min((current / limit) * 100, 999); // Cap at 999% for display
+}
+
+/**
+ * Get utilization status (traffic light) based on percentage
+ */
+export function getUtilizationStatus(percentage: number): UtilizationStatus {
+  if (percentage < UTILIZATION_THRESHOLDS.green) return 'green';
+  if (percentage < UTILIZATION_THRESHOLDS.yellow) return 'yellow';
+  return 'red';
+}
+
+/**
+ * Get the effective limit for a project/service combination
+ */
+export function getEffectiveLimit(_projectId: string, serviceType: ServiceType): number {
+  // Always use account-level CF allowances for utilization calculations.
+  // This matches actual Cloudflare billing and provides accurate visibility.
+  // Project-specific budgets were removed 2026-01-15 - see PROJECT_ALLOWANCES comment.
+  return CF_ALLOWANCES[serviceType].monthlyLimit;
+}
+
+/**
+ * Calculate utilization data for a project
+ */
+export interface ProjectUtilization {
+  projectId: string;
+  projectName: string;
+  primaryResource: ServiceType;
+  currentUsage: number;
+  monthlyLimit: number;
+  utilizationPct: number;
+  status: UtilizationStatus;
+  unit: string;
+}
+
+/**
+ * Build utilization data for a project given current usage
+ */
+export function buildProjectUtilization(
+  projectId: string,
+  currentUsage: Record<ServiceType, number>
+): ProjectUtilization | null {
+  const projectConfig = PROJECT_ALLOWANCES.find((p) => p.projectId === projectId);
+  if (!projectConfig) return null;
+
+  const primaryResource = projectConfig.primaryResource;
+  const usage = currentUsage[primaryResource] ?? 0;
+  const limit = getEffectiveLimit(projectId, primaryResource);
+  const utilizationPct = calculateUtilizationPct(usage, limit);
+
+  return {
+    projectId,
+    projectName: projectConfig.projectName,
+    primaryResource,
+    currentUsage: usage,
+    monthlyLimit: limit,
+    utilizationPct,
+    status: getUtilizationStatus(utilizationPct),
+    unit: CF_ALLOWANCES[primaryResource].unit,
+  };
+}
+
+/**
+ * Calculate aggregate account-level utilization across all services
+ */
+export interface AccountUtilization {
+  totalMTDCost: number;
+  projectedMonthlyCost: number;
+  dailyBurnRate: number;
+  daysIntoMonth: number;
+  services: Record<
+    ServiceType,
+    {
+      current: number;
+      limit: number;
+      pct: number;
+      status: UtilizationStatus;
+    }
+  >;
+}
+
+/**
+ * Get the list of tracked project IDs
+ */
+export function getTrackedProjectIds(): string[] {
+  return PROJECT_ALLOWANCES.map((p) => p.projectId);
+}
+
+/**
+ * Get project display name by ID
+ */
+export function getProjectDisplayName(projectId: string): string {
+  const project = PROJECT_ALLOWANCES.find((p) => p.projectId === projectId);
+  return project?.projectName ?? projectId;
+}
+
+/**
+ * Simplified allowances for worker usage (limit + unit only)
+ * Used by platform-usage worker for utilization calculations.
+ */
+export type SimpleAllowanceType =
+  | 'workers'
+  | 'd1'
+  | 'kv'
+  | 'r2'
+  | 'vectorize'
+  | 'workersAI'
+  | 'durableObjects'
+  | 'queues';
+
+export const CF_SIMPLE_ALLOWANCES: Record<SimpleAllowanceType, { limit: number; unit: string }> = {
+  workers: { limit: CF_ALLOWANCES.workers.monthlyLimit, unit: CF_ALLOWANCES.workers.unit },
+  d1: { limit: CF_ALLOWANCES.d1.monthlyLimit, unit: CF_ALLOWANCES.d1.unit },
+  kv: { limit: CF_ALLOWANCES.kv.monthlyLimit, unit: CF_ALLOWANCES.kv.unit },
+  r2: { limit: CF_ALLOWANCES.r2.monthlyLimit, unit: CF_ALLOWANCES.r2.unit },
+  vectorize: { limit: CF_ALLOWANCES.vectorize.monthlyLimit, unit: CF_ALLOWANCES.vectorize.unit },
+  workersAI: { limit: CF_ALLOWANCES.workersAI.monthlyLimit, unit: CF_ALLOWANCES.workersAI.unit },
+  durableObjects: {
+    limit: CF_ALLOWANCES.durableObjects.monthlyLimit,
+    unit: CF_ALLOWANCES.durableObjects.unit,
+  },
+  queues: {
+    limit: CF_ALLOWANCES.queues.monthlyLimit,
+    unit: CF_ALLOWANCES.queues.unit,
+  },
+};
+
+// =============================================================================
+// GITHUB ALLOWANCES & PRICING
+// =============================================================================
+
+/**
+ * GitHub plan allowances (defaults by plan tier)
+ * These are dynamically fetched from the API but have fallbacks here.
+ *
+ * @see https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-actions/about-billing-for-github-actions
+ */
+export const GITHUB_ALLOWANCES = {
+  /** GitHub Free plan */
+  free: {
+    actionsMinutes: 2000, // 2,000 minutes/month (private repos)
+    actionsStorageGb: 0.5, // 500 MB storage
+    packagesStorageGb: 0.5, // 500 MB packages
+    packagesBandwidthGb: 1, // 1 GB bandwidth
+    lfsStorageGb: 1, // 1 GiB storage
+    lfsBandwidthGb: 1, // 1 GiB bandwidth/month
+  },
+  /** GitHub Pro plan (individual) */
+  pro: {
+    actionsMinutes: 3000, // 3,000 minutes/month
+    actionsStorageGb: 2, // 2 GB storage
+    packagesStorageGb: 2, // 2 GB packages
+    packagesBandwidthGb: 10, // 10 GB bandwidth
+    lfsStorageGb: 1, // 1 GiB storage
+    lfsBandwidthGb: 1, // 1 GiB bandwidth/month
+  },
+  /** GitHub Team plan */
+  team: {
+    actionsMinutes: 3000, // 3,000 minutes/month
+    actionsStorageGb: 2, // 2 GB storage
+    packagesStorageGb: 2, // 2 GB packages
+    packagesBandwidthGb: 10, // 10 GB bandwidth
+    lfsStorageGb: 1, // 1 GiB storage
+    lfsBandwidthGb: 1, // 1 GiB bandwidth/month
+  },
+  /** GitHub Enterprise Cloud plan */
+  enterprise: {
+    actionsMinutes: 50000, // 50,000 minutes/month
+    actionsStorageGb: 50, // 50 GB storage
+    packagesStorageGb: 50, // 50 GB packages
+    packagesBandwidthGb: 100, // 100 GB bandwidth
+    lfsStorageGb: 250, // 250 GiB storage
+    lfsBandwidthGb: 250, // 250 GiB bandwidth/month
+  },
+} as const;
+
+/**
+ * GitHub pricing for overages and paid features
+ * Prices are in USD per unit
+ *
+ * @see https://docs.github.com/en/billing/managing-billing-for-your-products/managing-billing-for-github-actions/about-billing-for-github-actions
+ */
+export const GITHUB_PRICING = {
+  /** Actions minute overage pricing (per minute, by runner type)
+   * Updated Jan 2026: GitHub reduced Actions pricing by up to 39%
+   * @see https://docs.github.com/en/billing/reference/actions-runner-pricing */
+  actions: {
+    linux: 0.006, // $0.006/minute for Linux (was $0.008)
+    macos: 0.062, // $0.062/minute for macOS (was $0.08)
+    windows: 0.01, // $0.010/minute for Windows (was $0.016)
+    /** Larger runners have multiplied pricing */
+    linuxLarge: 0.012, // 2x Linux for 4-core
+    linuxXLarge: 0.024, // 4x Linux for 8-core
+    gpuLinux: 0.07, // GPU-powered runners
+  },
+  /** Actions storage overage (per GB/month) */
+  actionsStorageGb: 0.25, // $0.25/GB/month
+  /** Packages storage overage (per GB/month) */
+  packagesStorageGb: 0.25, // $0.25/GB/month
+  /** Packages bandwidth overage (per GB) */
+  packagesBandwidthGb: 0.5, // $0.50/GB
+  /** Git LFS storage overage (per GiB/month) */
+  lfsStorageGb: 0.07, // $0.07/GiB/month
+  /** Git LFS bandwidth overage (per GiB) */
+  lfsBandwidthGb: 0.007, // $0.007/GiB
+  /** GitHub Enterprise Cloud (per user/month) */
+  ghecPerUser: 21, // $21/user/month
+  /** GitHub Advanced Security - Code Security (per active committer/month) */
+  ghasCodeSecurity: 49, // $49/active committer/month
+  /** GitHub Advanced Security - Secret Protection (per active committer/month) */
+  ghasSecretProtection: 31, // $31/active committer/month
+  /** GitHub Copilot Business (per user/month) */
+  copilotBusiness: 19, // $19/user/month
+  /** GitHub Copilot Enterprise (per user/month) */
+  copilotEnterprise: 39, // $39/user/month
+} as const;
+
+/**
+ * Get GitHub plan allowances by plan name
+ */
+export function getGitHubPlanAllowances(
+  planName: string
+): (typeof GITHUB_ALLOWANCES)[keyof typeof GITHUB_ALLOWANCES] {
+  const lowerPlan = planName.toLowerCase();
+  if (lowerPlan.includes('enterprise')) return GITHUB_ALLOWANCES.enterprise;
+  if (lowerPlan.includes('team')) return GITHUB_ALLOWANCES.team;
+  if (lowerPlan.includes('pro')) return GITHUB_ALLOWANCES.pro;
+  return GITHUB_ALLOWANCES.free;
+}