@littlebearapps/create-platform 1.0.0 → 1.1.0

package/templates/shared/workers/lib/analytics-engine.ts

@@ -0,0 +1,357 @@
+/**
+ * Analytics Engine SQL API Helper
+ *
+ * Provides helpers for querying Analytics Engine via the SQL API.
+ * Used by the daily rollup to aggregate SDK telemetry from PLATFORM_ANALYTICS.
+ *
+ * @module workers/lib/analytics-engine
+ */
+
+import { withExponentialBackoff } from '@littlebearapps/platform-sdk';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/**
+ * Analytics Engine SQL API response structure.
+ *
+ * The SQL API returns data in one of two formats:
+ * 1. Direct format (success): { meta: [...], data: [...], rows: N }
+ * 2. Wrapped format (via REST API): { success: true, result: { meta, data, rows } }
+ * 3. Error format: { errors: [...] }
+ */
+interface AnalyticsEngineResponse {
+  // Direct format (SQL API)
+  meta?: Array<{ name: string; type: string }>;
+  data?: unknown[];
+  rows?: number;
+  rows_before_limit_at_least?: number;
+
+  // Wrapped format (REST API)
+  success?: boolean;
+  errors?: Array<{ code: number; message: string }>;
+  result?: {
+    data: unknown[];
+    meta: Array<{ name: string; type: string }>;
+    rows: number;
+    rows_before_limit_at_least: number;
+  };
+}
+
+/**
+ * Daily usage aggregation from Analytics Engine
+ */
+export interface DailyUsageAggregation {
+  project_id: string;
+  feature_id: string;
+  d1_reads: number;
+  d1_writes: number;
+  d1_rows_read: number;
+  d1_rows_written: number;
+  kv_reads: number;
+  kv_writes: number;
+  kv_deletes: number;
+  kv_lists: number;
+  ai_requests: number;
+  ai_neurons: number;
+  vectorize_queries: number;
+  vectorize_inserts: number;
+  vectorize_deletes: number;
+  interaction_count: number;
+}
+
+// =============================================================================
+// ANALYTICS ENGINE SQL API CLIENT
+// =============================================================================
+
+/**
+ * Query Analytics Engine via the SQL API.
+ *
+ * @param accountId Cloudflare account ID
+ * @param apiToken Cloudflare API token with Analytics Engine read access
+ * @param sql SQL query to execute
+ * @returns Query results
+ */
+export async function queryAnalyticsEngine<T>(
+  accountId: string,
+  apiToken: string,
+  sql: string
+): Promise<T[]> {
+  const url = `https://api.cloudflare.com/client/v4/accounts/${accountId}/analytics_engine/sql`;
+
+  const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${apiToken}`,
+      'Content-Type': 'text/plain',
+    },
+    body: sql,
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Analytics Engine API error: ${response.status} - ${text}`);
+  }
+
+  const rawText = await response.text();
+  let data: AnalyticsEngineResponse;
+  try {
+    data = JSON.parse(rawText) as AnalyticsEngineResponse;
+  } catch {
+    throw new Error(`Analytics Engine returned invalid JSON: ${rawText.slice(0, 500)}`);
+  }
+
+  // Check for error response
+  if (data.errors && data.errors.length > 0) {
+    const errorMessages = data.errors.map((e) => e.message).join(', ');
+    throw new Error(`Analytics Engine query failed: ${errorMessages}`);
+  }
+
+  // Handle both response formats:
+  // 1. Direct format: { meta, data, rows }
+  // 2. Wrapped format: { success, result: { meta, data, rows } }
+  const meta = data.meta ?? data.result?.meta;
+  const resultData = data.data ?? data.result?.data;
+
+  // Validate response structure
+  if (!meta || !resultData) {
+    throw new Error(
+      `Analytics Engine response missing expected fields. ` +
+        `Got keys: ${JSON.stringify(Object.keys(data))}`
+    );
+  }
+
+  // Map the result data to typed objects using column metadata
+  // Analytics Engine can return data in two formats:
+  // 1. Array of arrays: [[val1, val2], [val1, val2]] - needs column mapping
+  // 2. Array of objects: [{col1: val1, col2: val2}, ...] - already in object format
+  const columns = meta.map((m) => m.name);
+
+  return resultData.map((row) => {
+    // If row is already an object (not an array), return it directly
+    if (row !== null && typeof row === 'object' && !Array.isArray(row)) {
+      return row as T;
+    }
+
+    // Row is an array - map using column metadata
+    const rowArray = row as unknown[];
+    const obj: Record<string, unknown> = {};
+    columns.forEach((col, i) => {
+      obj[col] = rowArray[i];
+    });
+    return obj as T;
+  });
+}
+
+/**
+ * Get daily usage aggregation from Analytics Engine.
+ * Queries the PLATFORM_ANALYTICS dataset for yesterday's telemetry data.
+ *
+ * @param accountId Cloudflare account ID
+ * @param apiToken Cloudflare API token
+ * @param datasetName Analytics Engine dataset name (default: platform-analytics)
+ * @returns Aggregated usage by project and feature
+ */
+export async function getDailyUsageFromAnalyticsEngine(
+  accountId: string,
+  apiToken: string,
+  datasetName = 'platform-analytics'
+): Promise<DailyUsageAggregation[]> {
+  // Query for yesterday's data (00:00:00 to 23:59:59 UTC)
+  // Analytics Engine uses blob1-20 and double1-20 naming convention
+  //
+  // Data schema from queue handler (platform-usage.ts):
+  // blobs: [project, category, feature]  (feature_key is in indexes)
+  // doubles: [d1Writes, d1Reads, kvReads, kvWrites, doRequests, doGbSeconds,
+  //           r2ClassA, r2ClassB, aiNeurons, queueMessages, requests, cpuMs,
+  //           d1RowsRead, d1RowsWritten, kvDeletes, kvLists, aiRequests,
+  //           vectorizeQueries, vectorizeInserts, workflowInvocations]
+  // indexes: [feature_key]
+  //
+  // NOTE: Table name must be quoted because it contains a hyphen
+  const sql = `
+    SELECT
+      blob1 as project_id,
+      index1 as feature_id,
+      SUM(double2) as d1_reads,
+      SUM(double1) as d1_writes,
+      SUM(double13) as d1_rows_read,
+      SUM(double14) as d1_rows_written,
+      SUM(double3) as kv_reads,
+      SUM(double4) as kv_writes,
+      SUM(double15) as kv_deletes,
+      SUM(double16) as kv_lists,
+      SUM(double17) as ai_requests,
+      SUM(double9) as ai_neurons,
+      SUM(double18) as vectorize_queries,
+      SUM(double19) as vectorize_inserts,
+      0 as vectorize_deletes,
+      count() as interaction_count
+    FROM "${datasetName}"
+    WHERE timestamp >= NOW() - INTERVAL '1' DAY
+    GROUP BY project_id, feature_id
+    ORDER BY project_id, feature_id
+  `;
+
+  return queryAnalyticsEngine<DailyUsageAggregation>(accountId, apiToken, sql);
+}
+
+/**
+ * Get aggregated project-level usage from Analytics Engine.
+ * Groups all features by project for higher-level reporting.
+ *
+ * @param accountId Cloudflare account ID
+ * @param apiToken Cloudflare API token
+ * @param datasetName Analytics Engine dataset name
+ * @returns Aggregated usage by project
+ */
+export async function getProjectUsageFromAnalyticsEngine(
+  accountId: string,
+  apiToken: string,
+  datasetName = 'platform-analytics'
+): Promise<Omit<DailyUsageAggregation, 'feature_id'>[]> {
+  // NOTE: Table name must be quoted because it contains a hyphen
+  // Schema matches METRIC_FIELDS order from platform-sdk/constants.ts
+  const sql = `
+    SELECT
+      blob1 as project_id,
+      SUM(double2) as d1_reads,
+      SUM(double1) as d1_writes,
+      SUM(double13) as d1_rows_read,
+      SUM(double14) as d1_rows_written,
+      SUM(double3) as kv_reads,
+      SUM(double4) as kv_writes,
+      SUM(double15) as kv_deletes,
+      SUM(double16) as kv_lists,
+      SUM(double17) as ai_requests,
+      SUM(double9) as ai_neurons,
+      SUM(double18) as vectorize_queries,
+      SUM(double19) as vectorize_inserts,
+      0 as vectorize_deletes,
+      count() as interaction_count
+    FROM "${datasetName}"
+    WHERE timestamp >= NOW() - INTERVAL '1' DAY
+    GROUP BY project_id
+    ORDER BY project_id
+  `;
+
+  return queryAnalyticsEngine<Omit<DailyUsageAggregation, 'feature_id'>>(accountId, apiToken, sql);
+}
+
+// =============================================================================
+// TIME-BUCKETED QUERIES
+// =============================================================================
+
+/**
+ * Time-bucketed usage data from Analytics Engine.
+ * Aggregates metrics by time bucket (hour/day) and project.
+ */
+export interface TimeBucketedUsage {
+  time_bucket: string;
+  project_id: string;
+  d1_writes: number;
+  d1_reads: number;
+  d1_rows_read: number;
+  d1_rows_written: number;
+  kv_reads: number;
+  kv_writes: number;
+  kv_deletes: number;
+  kv_lists: number;
+  do_requests: number;
+  do_gb_seconds: number;
+  r2_class_a: number;
+  r2_class_b: number;
+  ai_neurons: number;
+  ai_requests: number;
+  queue_messages: number;
+  requests: number;
+  cpu_ms: number;
+  vectorize_queries: number;
+  vectorize_inserts: number;
+  workflow_invocations: number;
+  interaction_count: number;
+}
+
+/**
+ * Query parameters for time-bucketed usage.
+ */
+export interface TimeBucketQueryParams {
+  period: '24h' | '7d' | '30d';
+  groupBy: 'hour' | 'day';
+  project?: string;
+}
+
+/**
+ * Query usage by time bucket from Analytics Engine.
+ * Returns aggregated metrics grouped by time interval (hour/day) and project.
+ *
+ * @param accountId Cloudflare account ID
+ * @param apiToken Cloudflare API token
+ * @param params Query parameters (period, groupBy, optional project filter)
+ * @param datasetName Analytics Engine dataset name
+ * @returns Time-bucketed usage data
+ */
+export async function queryUsageByTimeBucket(
+  accountId: string,
+  apiToken: string,
+  params: TimeBucketQueryParams,
+  datasetName = 'platform-analytics'
+): Promise<TimeBucketedUsage[]> {
+  // Determine interval based on groupBy
+  const interval = params.groupBy === 'hour' ? 'HOUR' : 'DAY';
+
+  // Map period to interval parts (number and unit must be separate for Analytics Engine)
+  const periodMap: Record<string, { num: string; unit: string }> = {
+    '24h': { num: '1', unit: 'DAY' },
+    '7d': { num: '7', unit: 'DAY' },
+    '30d': { num: '30', unit: 'DAY' },
+  };
+  const periodParts = periodMap[params.period] ?? { num: '1', unit: 'DAY' };
+
+  // Build project filter clause
+  const projectFilter = params.project ? `AND blob1 = '${params.project}'` : '';
+
+  // NOTE: Table name must be quoted because it contains a hyphen
+  // Analytics Engine columns map (from platform-sdk/constants.ts METRIC_FIELDS):
+  // double1=d1Writes, double2=d1Reads, double3=kvReads, double4=kvWrites,
+  // double5=doRequests, double6=doGbSeconds, double7=r2ClassA, double8=r2ClassB,
+  // double9=aiNeurons, double10=queueMessages, double11=requests, double12=cpuMs,
+  // double13=d1RowsRead, double14=d1RowsWritten, double15=kvDeletes, double16=kvLists,
+  // double17=aiRequests, double18=vectorizeQueries, double19=vectorizeInserts,
+  // double20=workflowInvocations
+  // blobs: blob1=project, blob2=category, blob3=feature
+  const sql = `
+    SELECT
+      toStartOfInterval(timestamp, INTERVAL '1' ${interval}) as time_bucket,
+      blob1 as project_id,
+      SUM(double1) as d1_writes,
+      SUM(double2) as d1_reads,
+      SUM(double13) as d1_rows_read,
+      SUM(double14) as d1_rows_written,
+      SUM(double3) as kv_reads,
+      SUM(double4) as kv_writes,
+      SUM(double15) as kv_deletes,
+      SUM(double16) as kv_lists,
+      SUM(double5) as do_requests,
+      SUM(double6) as do_gb_seconds,
+      SUM(double7) as r2_class_a,
+      SUM(double8) as r2_class_b,
+      SUM(double9) as ai_neurons,
+      SUM(double17) as ai_requests,
+      SUM(double10) as queue_messages,
+      SUM(double11) as requests,
+      SUM(double12) as cpu_ms,
+      SUM(double18) as vectorize_queries,
+      SUM(double19) as vectorize_inserts,
+      SUM(double20) as workflow_invocations,
+      count() as interaction_count
+    FROM "${datasetName}"
+    WHERE timestamp >= NOW() - INTERVAL '${periodParts.num}' ${periodParts.unit}
+    ${projectFilter}
+    GROUP BY time_bucket, project_id
+    ORDER BY time_bucket ASC, project_id ASC
+  `;
+
+  return queryAnalyticsEngine<TimeBucketedUsage>(accountId, apiToken, sql);
+}

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-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-sdk/middleware';