@littlebearapps/platform-admin-sdk 1.0.0

package/templates/shared/workers/lib/billing.ts

@@ -0,0 +1,293 @@
+/**
+ * Billing Period Utilities
+ *
+ * Provides billing-cycle-aware calculations for accurate allowance proration.
+ * Supports both calendar-month and mid-month billing cycles.
+ *
+ * @see https://developers.cloudflare.com/workers/platform/pricing/
+ */
+
+/**
+ * Billing period information
+ */
+export interface BillingPeriod {
+  /** Start date of the current billing period */
+  startDate: Date;
+  /** End date of the current billing period */
+  endDate: Date;
+  /** Total days in this billing period */
+  daysInPeriod: number;
+  /** Days elapsed since billing period started */
+  daysElapsed: number;
+  /** Days remaining until billing period ends */
+  daysRemaining: number;
+  /** Progress through billing period (0-1) */
+  progress: number;
+}
+
+/**
+ * Plan types supported by Cloudflare
+ */
+export type PlanType = 'free' | 'paid' | 'enterprise';
+
+/**
+ * Billing settings from D1
+ */
+export interface BillingSettings {
+  accountId: string;
+  planType: PlanType;
+  billingCycleDay: number; // 1-28 or 0 for calendar month
+  billingCurrency: string;
+  baseCostMonthly: number;
+  notes?: string;
+}
+
+/**
+ * Calculate the billing period boundaries for a given reference date.
+ *
+ * @param billingCycleDay - Day of month billing starts (1-28) or 0 for calendar month
+ * @param refDate - Reference date (defaults to now)
+ * @returns Billing period information
+ *
+ * @example
+ * // Calendar month billing (billing_cycle_day = 0 or 1)
+ * calculateBillingPeriod(1, new Date('2026-01-15'))
+ * // Returns: startDate: Jan 1, endDate: Jan 31, daysInPeriod: 31
+ *
+ * @example
+ * // Mid-month billing (billing_cycle_day = 15)
+ * calculateBillingPeriod(15, new Date('2026-01-20'))
+ * // Returns: startDate: Jan 15, endDate: Feb 14, daysInPeriod: 31
+ */
+export function calculateBillingPeriod(
+  billingCycleDay: number,
+  refDate = new 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) {
+      // We're in the period that started this month
+      startDate = new Date(year, month, cycleDay);
+      endDate = new Date(year, month + 1, cycleDay - 1);
+    } else {
+      // We're in the period that started last month
+      startDate = new Date(year, month - 1, cycleDay);
+      endDate = new Date(year, month, cycleDay - 1);
+    }
+  }
+
+  // Calculate days
+  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,
+    endDate,
+    daysInPeriod,
+    daysElapsed,
+    daysRemaining,
+    progress,
+  };
+}
+
+/**
+ * Prorate a monthly allowance based on query period vs billing period.
+ *
+ * @param monthlyAllowance - Full monthly allowance (e.g., 10M Workers requests)
+ * @param periodDays - Number of days in the query period (e.g., 1 for 24h, 7 for 7d)
+ * @param billingDays - Total days in the billing period (default 30)
+ * @returns Prorated allowance for the query period
+ *
+ * @example
+ * // 24h query against 10M monthly allowance
+ * prorateAllowance(10_000_000, 1, 30)
+ * // Returns: 333,333 (1/30th of monthly)
+ *
+ * @example
+ * // 7d query against 50M monthly allowance
+ * prorateAllowance(50_000_000, 7, 31)
+ * // Returns: 11,290,323 (7/31ths of monthly)
+ */
+export function prorateAllowance(
+  monthlyAllowance: number,
+  periodDays: number,
+  billingDays = 30
+): number {
+  if (billingDays <= 0) return monthlyAllowance;
+  if (periodDays >= billingDays) return monthlyAllowance;
+  return Math.round(monthlyAllowance * (periodDays / billingDays));
+}
+
+/**
+ * Calculate billable usage after subtracting prorated allowance.
+ *
+ * @param usage - Raw usage for the period
+ * @param monthlyAllowance - Full monthly allowance
+ * @param periodDays - Number of days in the query period
+ * @param billingDays - Total days in the billing period (default 30)
+ * @returns Object with raw, prorated allowance, billable usage, and percentage
+ *
+ * @example
+ * // 500K requests in 24h against 10M monthly allowance
+ * calculateBillableUsage(500_000, 10_000_000, 1, 30)
+ * // Returns: { raw: 500000, proratedAllowance: 333333, billable: 166667, pctOfAllowance: 150 }
+ */
+export function calculateBillableUsage(
+  usage: number,
+  monthlyAllowance: number,
+  periodDays: number,
+  billingDays = 30
+): {
+  raw: number;
+  proratedAllowance: number;
+  billable: number;
+  pctOfAllowance: number;
+} {
+  const proratedAllowance = prorateAllowance(monthlyAllowance, periodDays, billingDays);
+  const billable = Math.max(0, usage - proratedAllowance);
+  const pctOfAllowance = proratedAllowance > 0 ? (usage / proratedAllowance) * 100 : 0;
+
+  return {
+    raw: usage,
+    proratedAllowance,
+    billable,
+    pctOfAllowance,
+  };
+}
+
+/**
+ * Get the default billing settings.
+ * Used as fallback when D1 data is unavailable.
+ */
+export function getDefaultBillingSettings(): BillingSettings {
+  return {
+    accountId: 'default',
+    planType: 'paid',
+    billingCycleDay: 1, // Calendar month
+    billingCurrency: 'USD',
+    baseCostMonthly: 5.0, // Workers Paid Plan
+    notes: 'Default billing settings',
+  };
+}
+
+/**
+ * Calculate fair share allowance allocation for a project.
+ *
+ * Uses proportional fair share: each project gets a share of the total
+ * allowance proportional to their share of total usage.
+ *
+ * @param projectUsage - Usage for this project
+ * @param totalAccountUsage - Total usage across all projects
+ * @param monthlyAllowance - Total monthly allowance for the account
+ * @returns Object with allowance share and billable usage
+ */
+export function calculateProjectAllowanceShare(
+  projectUsage: number,
+  totalAccountUsage: number,
+  monthlyAllowance: number
+): {
+  share: number;
+  billable: number;
+  proportion: number;
+} {
+  if (totalAccountUsage <= 0) {
+    return { share: 0, billable: 0, proportion: 0 };
+  }
+
+  const proportion = projectUsage / totalAccountUsage;
+  const share = monthlyAllowance * proportion;
+  const billable = Math.max(0, projectUsage - share);
+
+  return {
+    share: Math.round(share),
+    billable: Math.round(billable),
+    proportion,
+  };
+}
+
+/**
+ * Billing window with ISO date strings for SQL queries.
+ */
+export interface BillingWindow {
+  /** Start date as YYYY-MM-DD string */
+  startDate: string;
+  /** End date as YYYY-MM-DD string */
+  endDate: string;
+  /** Days elapsed in current period */
+  daysElapsed: number;
+  /** Total days in billing period */
+  daysInPeriod: number;
+  /** Progress through period (0-1) */
+  progress: number;
+}
+
+/**
+ * Get billing window dates for SQL queries.
+ *
+ * Convenience wrapper around calculateBillingPeriod that returns
+ * ISO date strings ready for D1 queries.
+ *
+ * @param anchorDay - Day of month billing resets (1-28) or 0/1 for calendar month
+ * @param refDate - Reference date (defaults to now)
+ * @returns Billing window with date strings
+ */
+export function getBillingWindow(anchorDay: number, refDate = new Date()): BillingWindow {
+  const period = calculateBillingPeriod(anchorDay, refDate);
+
+  // Format as YYYY-MM-DD in local time (not UTC) to match D1 date storage
+  const formatLocalDate = (date: Date): string => {
+    const y = date.getFullYear();
+    const m = String(date.getMonth() + 1).padStart(2, '0');
+    const d = String(date.getDate()).padStart(2, '0');
+    return `${y}-${m}-${d}`;
+  };
+
+  return {
+    startDate: formatLocalDate(period.startDate),
+    endDate: formatLocalDate(period.endDate),
+    daysElapsed: period.daysElapsed,
+    daysInPeriod: period.daysInPeriod,
+    progress: period.progress,
+  };
+}
+
+/**
+ * Format billing period for display.
+ *
+ * @param period - Billing period from calculateBillingPeriod
+ * @returns Formatted string like "Jan 1 - Jan 31"
+ */
+export function formatBillingPeriod(period: BillingPeriod): string {
+  const formatter = new Intl.DateTimeFormat('en-AU', { month: 'short', day: 'numeric' });
+  return `${formatter.format(period.startDate)} - ${formatter.format(period.endDate)}`;
+}
+
+/**
+ * Get billing countdown text.
+ *
+ * @param daysRemaining - Days remaining in billing period
+ * @returns Human-readable countdown string
+ */
+export 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`;
+}

package/templates/shared/workers/lib/circuit-breaker-middleware.ts

@@ -0,0 +1,25 @@
+/// <reference types="@cloudflare/workers-types" />
+
+/**
+ * Circuit Breaker Middleware -- Thin Re-export from Platform SDK
+ *
+ * All logic lives in @littlebearapps/platform-consumer-sdk/middleware.
+ * This file re-exports with the original names for backward compatibility.
+ *
+ * @see packages/platform-sdk/src/middleware.ts
+ */
+
+// Re-export with original names (SDK uses prefixed names)
+export {
+  PROJECT_CB_STATUS as CB_STATUS,
+  CB_PROJECT_KEYS,
+  CB_ERROR_CODES,
+  BUDGET_STATUS_HEADER,
+  checkProjectCircuitBreaker as checkCircuitBreaker,
+  checkProjectCircuitBreakerDetailed as checkCircuitBreakerDetailed,
+  createCircuitBreakerMiddleware,
+  getCircuitBreakerStates,
+  type CircuitBreakerStatusValue,
+  type CircuitBreakerCheckResult,
+  type CircuitBreakerErrorResponse,
+} from '@littlebearapps/platform-consumer-sdk/middleware';

package/templates/shared/workers/lib/control.ts

@@ -0,0 +1,292 @@
+/// <reference types="@cloudflare/workers-types" />
+
+/**
+ * PID Controller for Intelligent Degradation
+ *
+ * Provides smooth throttle rate calculation (0.0-1.0) instead of binary ON/OFF.
+ * State is stored in KV, making the controller stateless per invocation.
+ *
+ * Key principle: PID provides smooth degradation, circuit breakers remain the emergency stop.
+ */
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/**
+ * PID controller gains and configuration.
+ * Tuned for budget-based throttling where:
+ * - setpoint (0.70) = target 70% budget utilisation
+ * - Output range [0, 1] = throttle rate (0=no throttle, 1=full throttle)
+ */
+export interface PIDConfig {
+  /** Proportional gain - responds to current error */
+  kp: number;
+  /** Integral gain - responds to accumulated error */
+  ki: number;
+  /** Derivative gain - responds to rate of change */
+  kd: number;
+  /** Target budget utilisation (0.0-1.0) */
+  setpoint: number;
+  /** Minimum output value (default: 0) */
+  outputMin: number;
+  /** Maximum output value (default: 1) */
+  outputMax: number;
+  /** Maximum integral accumulation to prevent windup */
+  integralMax: number;
+}
+
+/**
+ * Persisted PID state stored in KV.
+ * Key: STATE:PID:{feature_id}
+ */
+export interface PIDState {
+  /** Accumulated error (integral term) */
+  integral: number;
+  /** Previous error for derivative calculation */
+  prevError: number;
+  /** Last update timestamp (ms) */
+  lastUpdate: number;
+  /** Current throttle rate output */
+  throttleRate: number;
+}
+
+/**
+ * Input for PID computation.
+ */
+export interface PIDInput {
+  /** Current budget utilisation (0.0-1.0+, can exceed 1.0 if over budget) */
+  currentUsage: number;
+  /** Time since last update in milliseconds */
+  deltaTimeMs: number;
+}
+
+/**
+ * Output from PID computation.
+ */
+export interface PIDOutput {
+  /** Computed throttle rate (0.0-1.0) */
+  throttleRate: number;
+  /** Updated state to persist */
+  newState: PIDState;
+  /** Debug info for monitoring */
+  debug: {
+    error: number;
+    pTerm: number;
+    iTerm: number;
+    dTerm: number;
+  };
+}
+
+// =============================================================================
+// DEFAULT CONFIGURATION
+// =============================================================================
+
+/**
+ * Default PID configuration tuned for budget-based throttling.
+ *
+ * Rationale:
+ * - kp=0.5: Moderate response to current error (50% of error -> throttle change)
+ * - ki=0.1: Slow integral to avoid oscillation, correct steady-state error
+ * - kd=0.05: Light derivative to dampen sudden changes
+ * - setpoint=0.70: Target 70% budget utilisation, leaving 30% headroom
+ * - integralMax=2.0: Prevent integral windup during sustained over-budget
+ */
+export const DEFAULT_PID_CONFIG: PIDConfig = {
+  kp: 0.5,
+  ki: 0.1,
+  kd: 0.05,
+  setpoint: 0.7,
+  outputMin: 0,
+  outputMax: 1,
+  integralMax: 2.0,
+};
+
+/**
+ * Create a fresh PID state (for new features or reset).
+ */
+export function createPIDState(): PIDState {
+  return {
+    integral: 0,
+    prevError: 0,
+    lastUpdate: Date.now(),
+    throttleRate: 0,
+  };
+}
+
+// =============================================================================
+// PID COMPUTATION
+// =============================================================================
+
+/**
+ * Compute PID output for throttle rate.
+ *
+ * This is a stateless function - pass in current state, get new state back.
+ * The caller is responsible for persisting state to KV.
+ *
+ * @param state - Current PID state from KV (or fresh state for new features)
+ * @param input - Current usage and timing information
+ * @param config - PID configuration (defaults provided)
+ * @returns New throttle rate and updated state
+ *
+ * @example
+ * ```typescript
+ * const state = await getPIDState(featureId, env);
+ * const input = { currentUsage: 0.85, deltaTimeMs: 60000 };
+ * const output = computePID(state, input);
+ * await savePIDState(featureId, output.newState, env);
+ * ```
+ */
+export function computePID(
+  state: PIDState,
+  input: PIDInput,
+  config: PIDConfig = DEFAULT_PID_CONFIG
+): PIDOutput {
+  // Calculate error: positive = over budget, negative = under budget
+  // error > 0 means we need MORE throttling
+  const error = input.currentUsage - config.setpoint;
+
+  // Convert deltaTime to seconds for consistent gains regardless of update frequency
+  const dt = Math.max(input.deltaTimeMs / 1000, 0.001); // Minimum 1ms to avoid division issues
+
+  // Proportional term: immediate response to current error
+  const pTerm = config.kp * error;
+
+  // Integral term: accumulated error over time (with anti-windup)
+  let newIntegral = state.integral + error * dt;
+  // Clamp integral to prevent windup
+  newIntegral = Math.max(-config.integralMax, Math.min(config.integralMax, newIntegral));
+  const iTerm = config.ki * newIntegral;
+
+  // Derivative term: rate of change of error (damping)
+  const derivative = (error - state.prevError) / dt;
+  const dTerm = config.kd * derivative;
+
+  // Sum all terms
+  let output = pTerm + iTerm + dTerm;
+
+  // Clamp output to valid range
+  output = Math.max(config.outputMin, Math.min(config.outputMax, output));
+
+  // Create new state
+  const newState: PIDState = {
+    integral: newIntegral,
+    prevError: error,
+    lastUpdate: Date.now(),
+    throttleRate: output,
+  };
+
+  return {
+    throttleRate: output,
+    newState,
+    debug: {
+      error,
+      pTerm,
+      iTerm,
+      dTerm,
+    },
+  };
+}
+
+// =============================================================================
+// KV PERSISTENCE HELPERS
+// =============================================================================
+
+/**
+ * KV key for PID state.
+ */
+export function pidStateKey(featureId: string): string {
+  return `STATE:PID:${featureId}`;
+}
+
+/**
+ * KV key for throttle rate (read by SDK).
+ */
+export function throttleRateKey(featureId: string): string {
+  return `CONFIG:FEATURE:${featureId}:THROTTLE_RATE`;
+}
+
+/**
+ * Get PID state from KV, returning fresh state if not found.
+ */
+export async function getPIDState(featureId: string, kv: KVNamespace): Promise<PIDState> {
+  const key = pidStateKey(featureId);
+  const data = await kv.get(key, 'json');
+  if (data && typeof data === 'object') {
+    return data as PIDState;
+  }
+  return createPIDState();
+}
+
+/**
+ * Save PID state to KV with 24h TTL.
+ * Also writes throttle rate to separate key with 5min TTL for SDK consumption.
+ */
+export async function savePIDState(
+  featureId: string,
+  state: PIDState,
+  kv: KVNamespace
+): Promise<void> {
+  const stateKey = pidStateKey(featureId);
+  const rateKey = throttleRateKey(featureId);
+
+  // Save state with 24h TTL (for persistence across updates)
+  await kv.put(stateKey, JSON.stringify(state), { expirationTtl: 86400 });
+
+  // Save throttle rate separately with 5min TTL (for SDK quick access)
+  // Only write if throttle rate > 0 to avoid unnecessary KV writes
+  if (state.throttleRate > 0.001) {
+    await kv.put(rateKey, state.throttleRate.toString(), { expirationTtl: 300 });
+  } else {
+    // Delete the key if throttle rate is essentially 0
+    await kv.delete(rateKey);
+  }
+}
+
+/**
+ * Get current throttle rate for SDK consumption.
+ * Returns 0 if no throttle rate is set.
+ */
+export async function getThrottleRate(featureId: string, kv: KVNamespace): Promise<number> {
+  const key = throttleRateKey(featureId);
+  const value = await kv.get(key);
+  if (value) {
+    const rate = parseFloat(value);
+    return isNaN(rate) ? 0 : Math.max(0, Math.min(1, rate));
+  }
+  return 0;
+}
+
+// =============================================================================
+// UTILITY FUNCTIONS
+// =============================================================================
+
+/**
+ * Calculate budget utilisation from current usage and limit.
+ *
+ * @param currentUsage - Current period usage value
+ * @param budgetLimit - Budget limit for the period
+ * @returns Utilisation ratio (0.0-1.0+, can exceed 1.0 if over budget)
+ */
+export function calculateUtilisation(currentUsage: number, budgetLimit: number): number {
+  if (budgetLimit <= 0) return 0;
+  return currentUsage / budgetLimit;
+}
+
+/**
+ * Determine if PID update is needed based on time since last update.
+ *
+ * @param lastUpdate - Timestamp of last PID update (ms)
+ * @param minIntervalMs - Minimum interval between updates (default: 60s)
+ * @returns True if update is due
+ */
+export function shouldUpdatePID(lastUpdate: number, minIntervalMs: number = 60_000): boolean {
+  return Date.now() - lastUpdate >= minIntervalMs;
+}
+
+/**
+ * Format throttle rate for logging (percentage with 1 decimal).
+ */
+export function formatThrottleRate(rate: number): string {
+  return `${(rate * 100).toFixed(1)}%`;
+}