@littlebearapps/platform-admin-sdk 2.1.0 → 2.2.0

package/templates/shared/dashboard/src/pages/api/usage/billing-context.ts

@@ -0,0 +1,296 @@
+/**
+ * Billing Context API Endpoint
+ *
+ * Returns comprehensive billing cycle information with prorated allowances
+ * for accurate sub-monthly usage comparisons:
+ * - Current billing period dates (start, end)
+ * - Days elapsed and remaining
+ * - Plan type (free/paid/enterprise)
+ * - Prorated allowances for each Cloudflare service
+ *
+ * @module pages/api/usage/billing-context
+ * @created 2026-01-23
+ */
+
+import type { APIRoute } from 'astro';
+import type { D1Database } from '@cloudflare/workers-types';
+import { CF_ALLOWANCES, type ServiceType } from '../../../lib/usage/allowance-config';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+type PlanType = 'free' | 'paid' | 'enterprise';
+
+interface BillingSettings {
+  accountId: string;
+  planType: PlanType;
+  billingCycleDay: number;
+  billingCurrency: string;
+  baseCostMonthly: number;
+  notes: string | null;
+}
+
+interface BillingPeriod {
+  startDate: string; // ISO date
+  endDate: string; // ISO date
+  daysInPeriod: number;
+  daysElapsed: number;
+  daysRemaining: number;
+  progress: number; // 0-1
+}
+
+interface ServiceAllowance {
+  monthly: number;
+  prorated: number;
+  unit: string;
+  isPaidPlan: boolean;
+}
+
+interface BillingContextResponse {
+  success: true;
+  billingPeriod: BillingPeriod;
+  planType: PlanType;
+  allowances: Record<ServiceType, ServiceAllowance>;
+  periodFormatted: string;
+  countdownText: string;
+  prorationFactors: {
+    '24h': number;
+    '7d': number;
+    '30d': number;
+  };
+  timestamp: string;
+}
+
+interface ErrorResponse {
+  success: false;
+  error: string;
+  code: string;
+}
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+/**
+ * Calculate billing period boundaries
+ */
+function calculateBillingPeriod(billingCycleDay: number, refDate: Date): BillingPeriod {
+  // Normalise to calendar month if 0 or 1
+  const cycleDay = billingCycleDay <= 1 ? 1 : Math.min(billingCycleDay, 28);
+
+  const year = refDate.getFullYear();
+  const month = refDate.getMonth();
+  const day = refDate.getDate();
+
+  let startDate: Date;
+  let endDate: Date;
+
+  if (cycleDay === 1) {
+    // Calendar month billing
+    startDate = new Date(year, month, 1);
+    endDate = new Date(year, month + 1, 0); // Last day of current month
+  } else {
+    // Mid-month billing
+    if (day >= cycleDay) {
+      startDate = new Date(year, month, cycleDay);
+      endDate = new Date(year, month + 1, cycleDay - 1);
+    } else {
+      startDate = new Date(year, month - 1, cycleDay);
+      endDate = new Date(year, month, cycleDay - 1);
+    }
+  }
+
+  const daysInPeriod =
+    Math.round((endDate.getTime() - startDate.getTime()) / (1000 * 60 * 60 * 24)) + 1;
+  const daysElapsed =
+    Math.round((refDate.getTime() - startDate.getTime()) / (1000 * 60 * 60 * 24)) + 1;
+  const daysRemaining = Math.max(0, daysInPeriod - daysElapsed);
+  const progress = Math.min(1, daysElapsed / daysInPeriod);
+
+  return {
+    startDate: startDate.toISOString().slice(0, 10),
+    endDate: endDate.toISOString().slice(0, 10),
+    daysInPeriod,
+    daysElapsed,
+    daysRemaining,
+    progress,
+  };
+}
+
+/**
+ * Format billing period for display
+ */
+function formatBillingPeriod(period: BillingPeriod): string {
+  const formatter = new Intl.DateTimeFormat('en-AU', { month: 'short', day: 'numeric' });
+  const start = new Date(period.startDate);
+  const end = new Date(period.endDate);
+  return `${formatter.format(start)} - ${formatter.format(end)}`;
+}
+
+/**
+ * Get billing countdown text
+ */
+function getBillingCountdownText(daysRemaining: number): string {
+  if (daysRemaining <= 0) return 'Billing reset today';
+  if (daysRemaining === 1) return '1 day until billing reset';
+  return `${daysRemaining} days until billing reset`;
+}
+
+/**
+ * Prorate a monthly allowance for a given number of days
+ */
+function prorateAllowance(
+  monthlyAllowance: number,
+  periodDays: number,
+  billingDays: number
+): number {
+  if (billingDays <= 0) return monthlyAllowance;
+  if (periodDays >= billingDays) return monthlyAllowance;
+  if (monthlyAllowance === Infinity) return Infinity;
+  if (monthlyAllowance === 0) return 0;
+  return Math.round(monthlyAllowance * (periodDays / billingDays));
+}
+
+/**
+ * Build prorated allowances for all services
+ */
+function buildProratedAllowances(
+  daysInPeriod: number,
+  queryPeriodDays: number = 1
+): Record<ServiceType, ServiceAllowance> {
+  const result = {} as Record<ServiceType, ServiceAllowance>;
+
+  for (const [key, config] of Object.entries(CF_ALLOWANCES)) {
+    const serviceType = key as ServiceType;
+    result[serviceType] = {
+      monthly: config.monthlyLimit,
+      prorated: prorateAllowance(config.monthlyLimit, queryPeriodDays, daysInPeriod),
+      unit: config.unit,
+      isPaidPlan: config.isPaidPlan,
+    };
+  }
+
+  return result;
+}
+
+/**
+ * Load billing settings from D1 or return defaults
+ */
+async function loadBillingSettings(db: D1Database | undefined): Promise<BillingSettings> {
+  const defaults: BillingSettings = {
+    accountId: 'default',
+    planType: 'paid',
+    billingCycleDay: 1,
+    billingCurrency: 'USD',
+    baseCostMonthly: 5.0,
+    notes: 'Little Bear Apps - Workers Paid Plan',
+  };
+
+  if (!db) {
+    return defaults;
+  }
+
+  try {
+    const row = await db
+      .prepare(
+        `
+        SELECT
+          account_id,
+          plan_type,
+          billing_cycle_day,
+          billing_currency,
+          base_cost_monthly,
+          notes
+        FROM billing_settings
+        WHERE account_id = 'default'
+        LIMIT 1
+      `
+      )
+      .first<{
+        account_id: string;
+        plan_type: string;
+        billing_cycle_day: number;
+        billing_currency: string;
+        base_cost_monthly: number;
+        notes: string | null;
+      }>();
+
+    if (row) {
+      return {
+        accountId: row.account_id,
+        planType: row.plan_type as PlanType,
+        billingCycleDay: row.billing_cycle_day,
+        billingCurrency: row.billing_currency,
+        baseCostMonthly: row.base_cost_monthly,
+        notes: row.notes,
+      };
+    }
+  } catch (error) {
+    // Table may not exist yet (pre-migration)
+    console.warn('[BILLING-CONTEXT] billing_settings table not available, using defaults:', error);
+  }
+
+  return defaults;
+}
+
+// =============================================================================
+// HANDLER
+// =============================================================================
+
+export const GET: APIRoute = async ({ locals, url }) => {
+  // Get bindings from runtime environment
+  const env = locals.runtime?.env as { PLATFORM_DB?: D1Database } | undefined;
+
+  // Parse optional query period parameter (for prorated allowance calculation)
+  const periodParam = url.searchParams.get('period') ?? '24h';
+  let queryPeriodDays = 1;
+  if (periodParam === '7d') queryPeriodDays = 7;
+  else if (periodParam === '30d') queryPeriodDays = 30;
+
+  try {
+    const settings = await loadBillingSettings(env?.PLATFORM_DB);
+    const now = new Date();
+    const period = calculateBillingPeriod(settings.billingCycleDay, now);
+
+    // Build prorated allowances for the query period
+    const allowances = buildProratedAllowances(period.daysInPeriod, queryPeriodDays);
+
+    const response: BillingContextResponse = {
+      success: true,
+      billingPeriod: period,
+      planType: settings.planType,
+      allowances,
+      periodFormatted: formatBillingPeriod(period),
+      countdownText: getBillingCountdownText(period.daysRemaining),
+      prorationFactors: {
+        '24h': 1 / period.daysInPeriod,
+        '7d': Math.min(7 / period.daysInPeriod, 1),
+        '30d': Math.min(30 / period.daysInPeriod, 1),
+      },
+      timestamp: now.toISOString(),
+    };
+
+    return new Response(JSON.stringify(response), {
+      status: 200,
+      headers: {
+        'Content-Type': 'application/json',
+        'Cache-Control': 'public, max-age=3600', // 1 hour cache (billing period changes slowly)
+      },
+    });
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    console.error('[BILLING-CONTEXT] Error:', errorMessage);
+
+    const response: ErrorResponse = {
+      success: false,
+      error: 'Failed to load billing context',
+      code: 'INTERNAL_ERROR',
+    };
+
+    return new Response(JSON.stringify(response), {
+      status: 500,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+};