business-as-code 0.2.1 → 2.0.2

package/src/financials.ts

@@ -0,0 +1,352 @@
+/**
+ * Financial metrics and calculations
+ */
+
+import type { FinancialMetrics, FinancialStatement, Currency, TimePeriod } from './types.js'
+
+/**
+ * Calculate financial metrics from basic inputs
+ *
+ * @example
+ * ```ts
+ * const metrics = financials({
+ *   revenue: 1000000,
+ *   cogs: 300000,
+ *   operatingExpenses: 500000,
+ *   currency: 'USD',
+ *   period: 'monthly',
+ * })
+ *
+ * console.log(metrics.grossMargin) // 70%
+ * console.log(metrics.operatingMargin) // 20%
+ * console.log(metrics.netMargin) // 20%
+ * ```
+ */
+export function financials(metrics: Partial<FinancialMetrics>): FinancialMetrics {
+  const revenue = metrics.revenue || 0
+  const cogs = metrics.cogs || 0
+  const operatingExpenses = metrics.operatingExpenses || 0
+
+  // Calculate derived metrics
+  const grossProfit = revenue - cogs
+  const grossMargin = revenue > 0 ? (grossProfit / revenue) * 100 : 0
+
+  const operatingIncome = grossProfit - operatingExpenses
+  const operatingMargin = revenue > 0 ? (operatingIncome / revenue) * 100 : 0
+
+  const netIncome = metrics.netIncome ?? operatingIncome
+  const netMargin = revenue > 0 ? (netIncome / revenue) * 100 : 0
+
+  // EBITDA (simplified - would need D&A for accurate calculation)
+  const ebitda = metrics.ebitda ?? operatingIncome
+  const ebitdaMargin = revenue > 0 ? (ebitda / revenue) * 100 : 0
+
+  return {
+    ...metrics,
+    revenue,
+    cogs,
+    grossProfit,
+    grossMargin,
+    operatingExpenses,
+    operatingIncome,
+    operatingMargin,
+    netIncome,
+    netMargin,
+    ebitda,
+    ebitdaMargin,
+    currency: metrics.currency || 'USD',
+    period: metrics.period || 'monthly',
+  }
+}
+
+/**
+ * Calculate gross margin
+ */
+export function calculateGrossMargin(revenue: number, cogs: number): number {
+  if (revenue === 0) return 0
+  return ((revenue - cogs) / revenue) * 100
+}
+
+/**
+ * Calculate operating margin
+ */
+export function calculateOperatingMargin(
+  revenue: number,
+  cogs: number,
+  operatingExpenses: number
+): number {
+  if (revenue === 0) return 0
+  const operatingIncome = revenue - cogs - operatingExpenses
+  return (operatingIncome / revenue) * 100
+}
+
+/**
+ * Calculate net margin
+ */
+export function calculateNetMargin(revenue: number, netIncome: number): number {
+  if (revenue === 0) return 0
+  return (netIncome / revenue) * 100
+}
+
+/**
+ * Calculate EBITDA margin
+ */
+export function calculateEBITDAMargin(revenue: number, ebitda: number): number {
+  if (revenue === 0) return 0
+  return (ebitda / revenue) * 100
+}
+
+/**
+ * Calculate burn rate (monthly cash burn)
+ */
+export function calculateBurnRate(
+  cashStart: number,
+  cashEnd: number,
+  months: number
+): number {
+  if (months === 0) return 0
+  return (cashStart - cashEnd) / months
+}
+
+/**
+ * Calculate runway (months until cash runs out)
+ */
+export function calculateRunway(cash: number, monthlyBurnRate: number): number {
+  if (monthlyBurnRate === 0) return Infinity
+  if (monthlyBurnRate < 0) return Infinity // Company is profitable
+  return cash / monthlyBurnRate
+}
+
+/**
+ * Calculate customer acquisition cost (CAC)
+ */
+export function calculateCAC(marketingSpend: number, newCustomers: number): number {
+  if (newCustomers === 0) return 0
+  return marketingSpend / newCustomers
+}
+
+/**
+ * Calculate customer lifetime value (LTV)
+ */
+export function calculateLTV(
+  averageRevenuePerCustomer: number,
+  averageCustomerLifetimeMonths: number,
+  grossMarginPercent: number
+): number {
+  return averageRevenuePerCustomer * averageCustomerLifetimeMonths * (grossMarginPercent / 100)
+}
+
+/**
+ * Calculate LTV:CAC ratio
+ */
+export function calculateLTVtoCAC(ltv: number, cac: number): number {
+  if (cac === 0) return 0
+  return ltv / cac
+}
+
+/**
+ * Calculate payback period (months to recover CAC)
+ */
+export function calculatePaybackPeriod(cac: number, monthlyRevPerCustomer: number): number {
+  if (monthlyRevPerCustomer === 0) return 0
+  return cac / monthlyRevPerCustomer
+}
+
+/**
+ * Calculate annual recurring revenue (ARR)
+ */
+export function calculateARR(mrr: number): number {
+  return mrr * 12
+}
+
+/**
+ * Calculate monthly recurring revenue (MRR)
+ */
+export function calculateMRR(arr: number): number {
+  return arr / 12
+}
+
+/**
+ * Calculate revenue growth rate
+ */
+export function calculateGrowthRate(currentRevenue: number, previousRevenue: number): number {
+  if (previousRevenue === 0) return 0
+  return ((currentRevenue - previousRevenue) / previousRevenue) * 100
+}
+
+/**
+ * Calculate compound annual growth rate (CAGR)
+ */
+export function calculateCAGR(
+  beginningValue: number,
+  endingValue: number,
+  years: number
+): number {
+  if (beginningValue === 0 || years === 0) return 0
+  return (Math.pow(endingValue / beginningValue, 1 / years) - 1) * 100
+}
+
+/**
+ * Calculate return on investment (ROI)
+ */
+export function calculateROI(gain: number, cost: number): number {
+  if (cost === 0) return 0
+  return ((gain - cost) / cost) * 100
+}
+
+/**
+ * Calculate return on equity (ROE)
+ */
+export function calculateROE(netIncome: number, shareholderEquity: number): number {
+  if (shareholderEquity === 0) return 0
+  return (netIncome / shareholderEquity) * 100
+}
+
+/**
+ * Calculate return on assets (ROA)
+ */
+export function calculateROA(netIncome: number, totalAssets: number): number {
+  if (totalAssets === 0) return 0
+  return (netIncome / totalAssets) * 100
+}
+
+/**
+ * Calculate quick ratio (liquidity)
+ */
+export function calculateQuickRatio(
+  currentAssets: number,
+  inventory: number,
+  currentLiabilities: number
+): number {
+  if (currentLiabilities === 0) return 0
+  return (currentAssets - inventory) / currentLiabilities
+}
+
+/**
+ * Calculate current ratio (liquidity)
+ */
+export function calculateCurrentRatio(currentAssets: number, currentLiabilities: number): number {
+  if (currentLiabilities === 0) return 0
+  return currentAssets / currentLiabilities
+}
+
+/**
+ * Calculate debt-to-equity ratio
+ */
+export function calculateDebtToEquity(totalDebt: number, totalEquity: number): number {
+  if (totalEquity === 0) return 0
+  return totalDebt / totalEquity
+}
+
+/**
+ * Format currency value
+ */
+export function formatCurrency(amount: number, currency: Currency = 'USD'): string {
+  const symbol = getCurrencySymbol(currency)
+  const formatted = Math.abs(amount).toLocaleString(undefined, {
+    minimumFractionDigits: 0,
+    maximumFractionDigits: 2,
+  })
+
+  const sign = amount < 0 ? '-' : ''
+  return `${sign}${symbol}${formatted}`
+}
+
+/**
+ * Get currency symbol
+ */
+function getCurrencySymbol(currency: Currency): string {
+  const symbols: Record<string, string> = {
+    USD: '$',
+    EUR: '€',
+    GBP: '£',
+    JPY: '¥',
+    CNY: '¥',
+    CAD: 'C$',
+    AUD: 'A$',
+  }
+  return symbols[currency] || currency + ' '
+}
+
+/**
+ * Create a financial statement
+ */
+export function createStatement(
+  type: FinancialStatement['type'],
+  period: string,
+  lineItems: Record<string, number>,
+  currency: Currency = 'USD'
+): FinancialStatement {
+  return {
+    type,
+    period,
+    lineItems,
+    currency,
+  }
+}
+
+/**
+ * Get line item from financial statement
+ */
+export function getLineItem(statement: FinancialStatement, name: string): number {
+  return statement.lineItems[name] || 0
+}
+
+/**
+ * Compare financial metrics between periods
+ */
+export function compareMetrics(
+  current: FinancialMetrics,
+  previous: FinancialMetrics
+): Record<string, { change: number; changePercent: number }> {
+  const comparison: Record<string, { change: number; changePercent: number }> = {}
+
+  const keys: (keyof FinancialMetrics)[] = [
+    'revenue',
+    'grossProfit',
+    'operatingIncome',
+    'netIncome',
+    'ebitda',
+  ]
+
+  for (const key of keys) {
+    const currentVal = (current[key] as number) || 0
+    const previousVal = (previous[key] as number) || 0
+    const change = currentVal - previousVal
+    const changePercent = previousVal !== 0 ? (change / previousVal) * 100 : 0
+
+    comparison[key] = { change, changePercent }
+  }
+
+  return comparison
+}
+
+/**
+ * Validate financial metrics
+ */
+export function validateFinancials(
+  metrics: FinancialMetrics
+): { valid: boolean; errors: string[] } {
+  const errors: string[] = []
+
+  if (metrics.revenue && metrics.revenue < 0) {
+    errors.push('Revenue cannot be negative')
+  }
+
+  if (metrics.cogs && metrics.cogs < 0) {
+    errors.push('COGS cannot be negative')
+  }
+
+  if (metrics.operatingExpenses && metrics.operatingExpenses < 0) {
+    errors.push('Operating expenses cannot be negative')
+  }
+
+  if (metrics.revenue && metrics.cogs && metrics.cogs > metrics.revenue) {
+    errors.push('COGS cannot exceed revenue')
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  }
+}

package/src/goals.ts

@@ -0,0 +1,250 @@
+/**
+ * Business goals definition and tracking
+ */
+
+import type { GoalDefinition } from './types.js'
+
+/**
+ * Define a business goal with metrics and tracking
+ *
+ * @example
+ * ```ts
+ * const goals = Goals([
+ *   {
+ *     name: 'Launch MVP',
+ *     description: 'Ship minimum viable product to early customers',
+ *     category: 'strategic',
+ *     targetDate: new Date('2024-06-30'),
+ *     owner: 'Product Team',
+ *     metrics: ['User signups', 'Feature completion rate'],
+ *     status: 'in-progress',
+ *     progress: 65,
+ *   },
+ *   {
+ *     name: 'Achieve Product-Market Fit',
+ *     description: 'Validate product value with target customers',
+ *     category: 'strategic',
+ *     targetDate: new Date('2024-12-31'),
+ *     owner: 'CEO',
+ *     metrics: ['NPS > 50', 'Churn < 5%', '100+ paying customers'],
+ *     status: 'in-progress',
+ *     progress: 30,
+ *     dependencies: ['Launch MVP'],
+ *   },
+ * ])
+ * ```
+ */
+export function Goals(definitions: GoalDefinition[]): GoalDefinition[] {
+  return definitions.map(goal => validateAndNormalizeGoal(goal))
+}
+
+/**
+ * Define a single goal
+ */
+export function Goal(definition: GoalDefinition): GoalDefinition {
+  return validateAndNormalizeGoal(definition)
+}
+
+/**
+ * Validate and normalize a goal definition
+ */
+function validateAndNormalizeGoal(goal: GoalDefinition): GoalDefinition {
+  if (!goal.name) {
+    throw new Error('Goal name is required')
+  }
+
+  return {
+    ...goal,
+    category: goal.category || 'operational',
+    status: goal.status || 'not-started',
+    progress: goal.progress || 0,
+    metrics: goal.metrics || [],
+    dependencies: goal.dependencies || [],
+    metadata: goal.metadata || {},
+  }
+}
+
+/**
+ * Update goal progress
+ */
+export function updateProgress(goal: GoalDefinition, progress: number): GoalDefinition {
+  if (progress < 0 || progress > 100) {
+    throw new Error('Progress must be between 0 and 100')
+  }
+
+  // Auto-update status based on progress
+  let status = goal.status
+  if (progress === 0) {
+    status = 'not-started'
+  } else if (progress === 100) {
+    status = 'completed'
+  } else if (progress > 0) {
+    status = 'in-progress'
+  }
+
+  return {
+    ...goal,
+    progress,
+    status,
+  }
+}
+
+/**
+ * Mark goal as at-risk
+ */
+export function markAtRisk(goal: GoalDefinition): GoalDefinition {
+  return {
+    ...goal,
+    status: 'at-risk',
+  }
+}
+
+/**
+ * Mark goal as completed
+ */
+export function complete(goal: GoalDefinition): GoalDefinition {
+  return {
+    ...goal,
+    status: 'completed',
+    progress: 100,
+  }
+}
+
+/**
+ * Check if goal is overdue
+ */
+export function isOverdue(goal: GoalDefinition): boolean {
+  if (!goal.targetDate) return false
+  return new Date() > goal.targetDate && goal.status !== 'completed'
+}
+
+/**
+ * Get goals by category
+ */
+export function getGoalsByCategory(
+  goals: GoalDefinition[],
+  category: GoalDefinition['category']
+): GoalDefinition[] {
+  return goals.filter(g => g.category === category)
+}
+
+/**
+ * Get goals by status
+ */
+export function getGoalsByStatus(
+  goals: GoalDefinition[],
+  status: GoalDefinition['status']
+): GoalDefinition[] {
+  return goals.filter(g => g.status === status)
+}
+
+/**
+ * Get goals by owner
+ */
+export function getGoalsByOwner(goals: GoalDefinition[], owner: string): GoalDefinition[] {
+  return goals.filter(g => g.owner === owner)
+}
+
+/**
+ * Calculate overall progress across all goals
+ */
+export function calculateOverallProgress(goals: GoalDefinition[]): number {
+  if (goals.length === 0) return 0
+
+  const totalProgress = goals.reduce((sum, goal) => sum + (goal.progress || 0), 0)
+  return totalProgress / goals.length
+}
+
+/**
+ * Check for circular dependencies
+ */
+export function hasCircularDependencies(goals: GoalDefinition[]): boolean {
+  const goalMap = new Map(goals.map(g => [g.name, g]))
+
+  function checkCircular(goalName: string, visited = new Set<string>()): boolean {
+    if (visited.has(goalName)) return true
+
+    const goal = goalMap.get(goalName)
+    if (!goal || !goal.dependencies) return false
+
+    visited.add(goalName)
+
+    for (const dep of goal.dependencies) {
+      if (checkCircular(dep, new Set(visited))) {
+        return true
+      }
+    }
+
+    return false
+  }
+
+  return goals.some(goal => checkCircular(goal.name))
+}
+
+/**
+ * Get goals in dependency order
+ */
+export function sortByDependencies(goals: GoalDefinition[]): GoalDefinition[] {
+  const goalMap = new Map(goals.map(g => [g.name, g]))
+  const sorted: GoalDefinition[] = []
+  const visited = new Set<string>()
+
+  function visit(goalName: string) {
+    if (visited.has(goalName)) return
+
+    const goal = goalMap.get(goalName)
+    if (!goal) return
+
+    visited.add(goalName)
+
+    // Visit dependencies first
+    if (goal.dependencies) {
+      for (const dep of goal.dependencies) {
+        visit(dep)
+      }
+    }
+
+    sorted.push(goal)
+  }
+
+  for (const goal of goals) {
+    visit(goal.name)
+  }
+
+  return sorted
+}
+
+/**
+ * Validate goals
+ */
+export function validateGoals(goals: GoalDefinition[]): { valid: boolean; errors: string[] } {
+  const errors: string[] = []
+
+  for (const goal of goals) {
+    if (!goal.name) {
+      errors.push('Goal name is required')
+    }
+
+    if (goal.progress && (goal.progress < 0 || goal.progress > 100)) {
+      errors.push(`Goal ${goal.name} progress must be between 0 and 100`)
+    }
+
+    if (goal.dependencies) {
+      const goalNames = new Set(goals.map(g => g.name))
+      for (const dep of goal.dependencies) {
+        if (!goalNames.has(dep)) {
+          errors.push(`Goal ${goal.name} depends on unknown goal: ${dep}`)
+        }
+      }
+    }
+  }
+
+  if (hasCircularDependencies(goals)) {
+    errors.push('Circular dependencies detected in goals')
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  }
+}