@littlebearapps/platform-admin-sdk 1.0.0

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

@@ -0,0 +1,58 @@
+/**
+ * Shared Types
+ *
+ * Type definitions for project registry and resource mapping.
+ * These types are used by the platform-usage worker for project identification
+ * and resource attribution.
+ */
+
+/**
+ * Project record from the D1 project_registry table.
+ */
+export interface Project {
+  projectId: string;
+  displayName: string;
+  description: string | null;
+  color: string | null;
+  icon: string | null;
+  owner: string | null;
+  repoPath: string | null;
+  status: 'active' | 'archived' | 'development';
+  /** Primary resource type for utilization tracking (e.g., 'd1', 'workers', 'vectorize') */
+  primaryResource: ResourceType | null;
+  /** Custom limit for the primary resource (overrides global CF_ALLOWANCES) */
+  customLimit: number | null;
+  /** Full GitHub repository URL */
+  repoUrl: string | null;
+  /** GitHub repository identifier (e.g., 'org/repo') */
+  githubRepoId: string | null;
+}
+
+/**
+ * Resource mapping record from D1.
+ */
+export interface ResourceMapping {
+  resourceType: ResourceType;
+  resourceId: string;
+  resourceName: string;
+  projectId: string;
+  environment: 'production' | 'staging' | 'preview' | 'development';
+  notes: string | null;
+}
+
+/**
+ * Cloudflare resource types for project mapping.
+ */
+export type ResourceType =
+  | 'worker'
+  | 'd1'
+  | 'kv'
+  | 'r2'
+  | 'vectorize'
+  | 'queue'
+  | 'workflow'
+  | 'ai_gateway'
+  | 'workers_ai'
+  | 'durable_object'
+  | 'pages'
+  | 'analytics_engine';

package/templates/shared/workers/lib/telemetry-sampling.ts

@@ -0,0 +1,360 @@
+/// <reference types="@cloudflare/workers-types" />
+
+/**
+ * Reservoir Sampling for Latency Percentiles
+ *
+ * Implements Algorithm R for O(1) memory p99/p95 latency tracking.
+ * Maintains a fixed-size sample that represents the distribution of all seen values.
+ *
+ * Key properties:
+ * - O(1) memory: Fixed 100 samples (~800 bytes JSON)
+ * - O(1) per-sample: Constant time to add each sample
+ * - Unbiased: Each value has equal probability of being in the sample
+ *
+ * @see Vitter, J.S. (1985). "Random Sampling with a Reservoir"
+ */
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/**
+ * Reservoir state stored in KV.
+ * Key: STATE:RESERVOIR:{feature_id}
+ */
+export interface ReservoirState {
+  /** Fixed-size array of sampled values */
+  samples: number[];
+  /** Total number of values seen (for Algorithm R probability) */
+  totalSeen: number;
+  /** Timestamp of last update */
+  lastUpdate: number;
+  /** Pre-computed percentiles (updated on retrieval) */
+  percentiles?: PercentileResult;
+}
+
+/**
+ * Computed percentile values.
+ */
+export interface PercentileResult {
+  /** 50th percentile (median) */
+  p50: number;
+  /** 75th percentile */
+  p75: number;
+  /** 90th percentile */
+  p90: number;
+  /** 95th percentile */
+  p95: number;
+  /** 99th percentile */
+  p99: number;
+  /** Maximum value in sample */
+  max: number;
+  /** Minimum value in sample */
+  min: number;
+  /** Average of samples */
+  avg: number;
+  /** Sample count used for calculation */
+  sampleCount: number;
+  /** Total values seen (for context) */
+  totalSeen: number;
+}
+
+/**
+ * Configuration for reservoir sampling.
+ */
+export interface ReservoirConfig {
+  /** Maximum number of samples to keep (default: 100) */
+  maxSamples: number;
+}
+
+// =============================================================================
+// DEFAULT CONFIGURATION
+// =============================================================================
+
+/**
+ * Default reservoir configuration.
+ * 100 samples provides good percentile estimates while keeping KV payload small.
+ */
+export const DEFAULT_RESERVOIR_CONFIG: ReservoirConfig = {
+  maxSamples: 100,
+};
+
+/**
+ * Create a fresh reservoir state.
+ */
+export function createReservoirState(): ReservoirState {
+  return {
+    samples: [],
+    totalSeen: 0,
+    lastUpdate: Date.now(),
+  };
+}
+
+// =============================================================================
+// ALGORITHM R IMPLEMENTATION
+// =============================================================================
+
+/**
+ * Add a sample to the reservoir using Algorithm R.
+ *
+ * Algorithm R (Vitter 1985):
+ * - If reservoir not full: add sample directly
+ * - If reservoir full: with probability k/n, replace random sample
+ *   where k = reservoir size, n = total samples seen
+ *
+ * This ensures each of the n items has equal probability k/n of being in the sample.
+ *
+ * @param state - Current reservoir state
+ * @param value - New value to potentially add
+ * @param config - Reservoir configuration
+ * @returns Updated reservoir state (mutates in place for efficiency)
+ */
+export function addSample(
+  state: ReservoirState,
+  value: number,
+  config: ReservoirConfig = DEFAULT_RESERVOIR_CONFIG
+): ReservoirState {
+  state.totalSeen++;
+  state.lastUpdate = Date.now();
+
+  if (state.samples.length < config.maxSamples) {
+    // Reservoir not full - add directly
+    state.samples.push(value);
+  } else {
+    // Reservoir full - Algorithm R replacement
+    // Generate random index in range [0, totalSeen)
+    const j = Math.floor(Math.random() * state.totalSeen);
+
+    // If j < maxSamples, replace that element
+    if (j < config.maxSamples) {
+      state.samples[j] = value;
+    }
+    // Otherwise, the new sample is discarded
+  }
+
+  // Clear cached percentiles (will be recomputed on next read)
+  state.percentiles = undefined;
+
+  return state;
+}
+
+/**
+ * Add multiple samples efficiently.
+ * For batch processing of telemetry data.
+ */
+export function addSamples(
+  state: ReservoirState,
+  values: number[],
+  config: ReservoirConfig = DEFAULT_RESERVOIR_CONFIG
+): ReservoirState {
+  for (const value of values) {
+    addSample(state, value, config);
+  }
+  return state;
+}
+
+// =============================================================================
+// PERCENTILE CALCULATION
+// =============================================================================
+
+/**
+ * Calculate percentiles from the reservoir samples.
+ *
+ * Uses the "nearest rank" method for percentile calculation.
+ *
+ * @param state - Reservoir state with samples
+ * @returns Computed percentiles, or undefined if no samples
+ */
+export function calculatePercentiles(state: ReservoirState): PercentileResult | undefined {
+  if (state.samples.length === 0) {
+    return undefined;
+  }
+
+  // Sort samples for percentile calculation
+  const sorted = [...state.samples].sort((a, b) => a - b);
+  const n = sorted.length;
+
+  // Helper: get percentile value using nearest rank
+  const getPercentile = (p: number): number => {
+    const rank = Math.ceil((p / 100) * n) - 1;
+    return sorted[Math.max(0, Math.min(n - 1, rank))];
+  };
+
+  // Calculate statistics
+  const sum = sorted.reduce((a, b) => a + b, 0);
+
+  const result: PercentileResult = {
+    p50: getPercentile(50),
+    p75: getPercentile(75),
+    p90: getPercentile(90),
+    p95: getPercentile(95),
+    p99: getPercentile(99),
+    min: sorted[0],
+    max: sorted[n - 1],
+    avg: sum / n,
+    sampleCount: n,
+    totalSeen: state.totalSeen,
+  };
+
+  // Cache in state
+  state.percentiles = result;
+
+  return result;
+}
+
+/**
+ * Get percentiles, computing if not cached.
+ */
+export function getPercentiles(state: ReservoirState): PercentileResult | undefined {
+  if (state.percentiles) {
+    return state.percentiles;
+  }
+  return calculatePercentiles(state);
+}
+
+// =============================================================================
+// KV PERSISTENCE HELPERS
+// =============================================================================
+
+/**
+ * KV key for reservoir state.
+ */
+export function reservoirStateKey(featureId: string): string {
+  return `STATE:RESERVOIR:${featureId}`;
+}
+
+/**
+ * Get reservoir state from KV, returning fresh state if not found.
+ */
+export async function getReservoirState(
+  featureId: string,
+  kv: KVNamespace
+): Promise<ReservoirState> {
+  const key = reservoirStateKey(featureId);
+  const data = await kv.get(key, 'json');
+  if (data && typeof data === 'object') {
+    return data as ReservoirState;
+  }
+  return createReservoirState();
+}
+
+/**
+ * Save reservoir state to KV with 24h TTL.
+ */
+export async function saveReservoirState(
+  featureId: string,
+  state: ReservoirState,
+  kv: KVNamespace
+): Promise<void> {
+  const key = reservoirStateKey(featureId);
+
+  // Compute percentiles before saving for quick read access
+  if (!state.percentiles && state.samples.length > 0) {
+    calculatePercentiles(state);
+  }
+
+  await kv.put(key, JSON.stringify(state), { expirationTtl: 86400 });
+}
+
+// =============================================================================
+// UTILITY FUNCTIONS
+// =============================================================================
+
+/**
+ * Merge two reservoir states.
+ * Useful for combining data from multiple sources.
+ *
+ * Uses weighted random selection based on total samples seen.
+ */
+export function mergeReservoirs(
+  a: ReservoirState,
+  b: ReservoirState,
+  config: ReservoirConfig = DEFAULT_RESERVOIR_CONFIG
+): ReservoirState {
+  if (a.totalSeen === 0) return { ...b };
+  if (b.totalSeen === 0) return { ...a };
+
+  // Combine all samples
+  const combined = [...a.samples, ...b.samples];
+  const totalSeen = a.totalSeen + b.totalSeen;
+
+  // If combined fits in reservoir, keep all
+  if (combined.length <= config.maxSamples) {
+    return {
+      samples: combined,
+      totalSeen,
+      lastUpdate: Math.max(a.lastUpdate, b.lastUpdate),
+    };
+  }
+
+  // Otherwise, randomly select maxSamples
+  // Shuffle using Fisher-Yates
+  for (let i = combined.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [combined[i], combined[j]] = [combined[j], combined[i]];
+  }
+
+  return {
+    samples: combined.slice(0, config.maxSamples),
+    totalSeen,
+    lastUpdate: Math.max(a.lastUpdate, b.lastUpdate),
+  };
+}
+
+/**
+ * Reset reservoir state (clear all samples).
+ */
+export function resetReservoir(state: ReservoirState): ReservoirState {
+  state.samples = [];
+  state.totalSeen = 0;
+  state.lastUpdate = Date.now();
+  state.percentiles = undefined;
+  return state;
+}
+
+/**
+ * Get estimated memory usage of reservoir state in bytes.
+ * Useful for monitoring.
+ */
+export function estimateMemoryUsage(state: ReservoirState): number {
+  // Rough estimate: 8 bytes per number + JSON overhead
+  const samplesBytes = state.samples.length * 8;
+  const overheadBytes = 200; // JSON keys, metadata
+  return samplesBytes + overheadBytes;
+}
+
+/**
+ * Format percentiles for logging/display.
+ */
+export function formatPercentiles(percentiles: PercentileResult): string {
+  return (
+    `p50=${percentiles.p50.toFixed(2)}ms, ` +
+    `p95=${percentiles.p95.toFixed(2)}ms, ` +
+    `p99=${percentiles.p99.toFixed(2)}ms, ` +
+    `max=${percentiles.max.toFixed(2)}ms ` +
+    `(n=${percentiles.sampleCount}/${percentiles.totalSeen})`
+  );
+}
+
+/**
+ * Check if percentiles indicate potential latency issues.
+ *
+ * @param percentiles - Computed percentiles
+ * @param thresholds - Warning thresholds in ms
+ * @returns Warning message if thresholds exceeded, undefined otherwise
+ */
+export function checkLatencyThresholds(
+  percentiles: PercentileResult,
+  thresholds: { p95Warning: number; p99Warning: number } = { p95Warning: 100, p99Warning: 500 }
+): string | undefined {
+  const warnings: string[] = [];
+
+  if (percentiles.p95 > thresholds.p95Warning) {
+    warnings.push(`p95 (${percentiles.p95.toFixed(1)}ms) > ${thresholds.p95Warning}ms`);
+  }
+  if (percentiles.p99 > thresholds.p99Warning) {
+    warnings.push(`p99 (${percentiles.p99.toFixed(1)}ms) > ${thresholds.p99Warning}ms`);
+  }
+
+  return warnings.length > 0 ? warnings.join(', ') : undefined;
+}

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

@@ -0,0 +1,96 @@
+/**
+ * Example External Billing Collector
+ *
+ * Template for creating a new external provider collector.
+ * Copy this file and modify for your provider.
+ *
+ * Usage:
+ * 1. Copy this file to ./your-provider.ts
+ * 2. Implement the collect function
+ * 3. Register in ./index.ts COLLECTORS array
+ * 4. Add required API keys to your wrangler config
+ */
+
+import type { Env } from '../shared';
+import type { ExternalCollector } from './index';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/**
+ * Result type for your provider's metrics.
+ *
+ * For FLOW metrics (usage that accumulates): requests, tokens, compute units
+ * For STOCK metrics (point-in-time): balance remaining, quota remaining
+ */
+export interface ExampleUsageData {
+  /** Total requests made this billing period */
+  totalRequests: number;
+  /** Total cost in USD this billing period */
+  totalCostUsd: number;
+  /** Billing period start date (ISO) */
+  periodStart: string;
+  /** Billing period end date (ISO) */
+  periodEnd: string;
+}
+
+// =============================================================================
+// COLLECTOR IMPLEMENTATION
+// =============================================================================
+
+/**
+ * Collect usage data from your external provider.
+ *
+ * @param env - Worker environment (access API keys via env.YOUR_API_KEY)
+ * @returns Usage data from the provider
+ */
+export async function collectExampleUsage(env: Env): Promise<ExampleUsageData | null> {
+  // Check if API key is configured
+  const apiKey = (env as Record<string, unknown>)['EXAMPLE_API_KEY'] as string | undefined;
+  if (!apiKey) {
+    return null; // Provider not configured, skip silently
+  }
+
+  const response = await fetch('https://api.example.com/v1/usage', {
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      'Content-Type': 'application/json',
+    },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Example API returned ${response.status}: ${await response.text()}`);
+  }
+
+  const data = (await response.json()) as {
+    total_requests: number;
+    total_cost: number;
+    period_start: string;
+    period_end: string;
+  };
+
+  return {
+    totalRequests: data.total_requests,
+    totalCostUsd: data.total_cost,
+    periodStart: data.period_start,
+    periodEnd: data.period_end,
+  };
+}
+
+// =============================================================================
+// COLLECTOR REGISTRATION
+// =============================================================================
+
+/**
+ * Collector instance to register in ./index.ts COLLECTORS array.
+ *
+ * Example usage in index.ts:
+ *   import { exampleCollector } from './example';
+ *   const COLLECTORS = [exampleCollector];
+ */
+export const exampleCollector: ExternalCollector<ExampleUsageData | null> = {
+  name: 'example',
+  collect: collectExampleUsage,
+  defaultValue: null,
+};

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

@@ -0,0 +1,128 @@
+/**
+ * External Billing Collectors
+ *
+ * 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
+ *
+ * Metric types:
+ * - FLOW metrics: Usage that accumulates (requests, tokens) - safe to SUM
+ * - STOCK metrics: Point-in-time values (balance, quota) - do NOT SUM
+ */
+
+import type { Env } from '../shared';
+import { createLoggerFromEnv } from '@littlebearapps/platform-consumer-sdk';
+
+// =============================================================================
+// COLLECTOR INTERFACE
+// =============================================================================
+
+/**
+ * A single external metrics collector.
+ *
+ * Implement this interface for each external provider you want to track.
+ */
+export interface ExternalCollector<T> {
+  /** Unique name for the collector (used in logs and error arrays) */
+  name: string;
+  /** Collect metrics from the external provider */
+  collect: (env: Env) => Promise<T>;
+  /** Default value to return on failure */
+  defaultValue: T;
+}
+
+/**
+ * Combined external metrics from all providers.
+ *
+ * TODO: Add your provider result types here.
+ */
+export interface ExternalMetrics {
+  /** Results keyed by collector name */
+  results: Record<string, unknown>;
+  /** Collection timestamp */
+  collectedAt: string;
+  /** Providers that failed to collect */
+  errors: string[];
+}
+
+// =============================================================================
+// COLLECTOR REGISTRY
+// =============================================================================
+
+/**
+ * Register your collectors here.
+ *
+ * TODO: Import and add your collector modules. Example:
+ *
+ *   import { githubCollector } from './github';
+ *   import { openaiCollector } from './openai';
+ *
+ *   const COLLECTORS: ExternalCollector<unknown>[] = [
+ *     githubCollector,
+ *     openaiCollector,
+ *   ];
+ */
+const COLLECTORS: ExternalCollector<unknown>[] = [
+  // Add your collectors here
+];
+
+// =============================================================================
+// UNIFIED COLLECTION
+// =============================================================================
+
+/**
+ * Collect all external metrics in parallel.
+ *
+ * Each provider is collected independently - one failure doesn't affect others.
+ * Failed providers are logged and recorded in the errors array.
+ *
+ * @param env - Worker environment with API keys
+ * @returns Combined metrics from all providers
+ */
+export async function collectExternalMetrics(env: Env): Promise<ExternalMetrics> {
+  const log = createLoggerFromEnv(env, 'platform-usage', 'platform:usage:external');
+  const errors: string[] = [];
+
+  log.info('Starting external metrics collection', {
+    collectorCount: COLLECTORS.length,
+  });
+  const startTime = Date.now();
+
+  // Collect all providers in parallel
+  const collectorResults = await Promise.all(
+    COLLECTORS.map(async (collector) => {
+      try {
+        const result = await collector.collect(env);
+        return { name: collector.name, result };
+      } catch (e) {
+        log.error(`${collector.name} collection failed`, e instanceof Error ? e : undefined);
+        errors.push(collector.name);
+        return { name: collector.name, result: collector.defaultValue };
+      }
+    })
+  );
+
+  const results: Record<string, unknown> = {};
+  for (const { name, result } of collectorResults) {
+    results[name] = result;
+  }
+
+  const duration = Date.now() - startTime;
+  log.info('External metrics collection complete', {
+    durationMs: duration,
+    successCount: COLLECTORS.length - errors.length,
+    failedProviders: errors.length > 0 ? errors.join(', ') : 'none',
+  });
+
+  return {
+    results,
+    collectedAt: new Date().toISOString(),
+    errors,
+  };
+}