business-as-code 2.0.1 → 2.1.1

package/src/financials.js

@@ -0,0 +1,296 @@
+/**
+ * Financial metrics and calculations
+ */
+/**
+ * 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) {
+    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, cogs) {
+    if (revenue === 0)
+        return 0;
+    return ((revenue - cogs) / revenue) * 100;
+}
+/**
+ * Calculate operating margin
+ */
+export function calculateOperatingMargin(revenue, cogs, operatingExpenses) {
+    if (revenue === 0)
+        return 0;
+    const operatingIncome = revenue - cogs - operatingExpenses;
+    return (operatingIncome / revenue) * 100;
+}
+/**
+ * Calculate net margin
+ */
+export function calculateNetMargin(revenue, netIncome) {
+    if (revenue === 0)
+        return 0;
+    return (netIncome / revenue) * 100;
+}
+/**
+ * Calculate EBITDA margin
+ */
+export function calculateEBITDAMargin(revenue, ebitda) {
+    if (revenue === 0)
+        return 0;
+    return (ebitda / revenue) * 100;
+}
+/**
+ * Calculate burn rate (monthly cash burn)
+ */
+export function calculateBurnRate(cashStart, cashEnd, months) {
+    if (months === 0)
+        return 0;
+    return (cashStart - cashEnd) / months;
+}
+/**
+ * Calculate runway (months until cash runs out)
+ */
+export function calculateRunway(cash, monthlyBurnRate) {
+    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, newCustomers) {
+    if (newCustomers === 0)
+        return 0;
+    return marketingSpend / newCustomers;
+}
+/**
+ * Calculate customer lifetime value (LTV)
+ */
+export function calculateLTV(averageRevenuePerCustomer, averageCustomerLifetimeMonths, grossMarginPercent) {
+    return averageRevenuePerCustomer * averageCustomerLifetimeMonths * (grossMarginPercent / 100);
+}
+/**
+ * Calculate LTV:CAC ratio
+ */
+export function calculateLTVtoCAC(ltv, cac) {
+    if (cac === 0)
+        return 0;
+    return ltv / cac;
+}
+/**
+ * Calculate payback period (months to recover CAC)
+ */
+export function calculatePaybackPeriod(cac, monthlyRevPerCustomer) {
+    if (monthlyRevPerCustomer === 0)
+        return 0;
+    return cac / monthlyRevPerCustomer;
+}
+/**
+ * Calculate annual recurring revenue (ARR)
+ */
+export function calculateARR(mrr) {
+    return mrr * 12;
+}
+/**
+ * Calculate monthly recurring revenue (MRR)
+ */
+export function calculateMRR(arr) {
+    return arr / 12;
+}
+/**
+ * Calculate revenue growth rate
+ */
+export function calculateGrowthRate(currentRevenue, previousRevenue) {
+    if (previousRevenue === 0)
+        return 0;
+    return ((currentRevenue - previousRevenue) / previousRevenue) * 100;
+}
+/**
+ * Calculate compound annual growth rate (CAGR)
+ */
+export function calculateCAGR(beginningValue, endingValue, years) {
+    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, cost) {
+    if (cost === 0)
+        return 0;
+    return ((gain - cost) / cost) * 100;
+}
+/**
+ * Calculate return on equity (ROE)
+ */
+export function calculateROE(netIncome, shareholderEquity) {
+    if (shareholderEquity === 0)
+        return 0;
+    return (netIncome / shareholderEquity) * 100;
+}
+/**
+ * Calculate return on assets (ROA)
+ */
+export function calculateROA(netIncome, totalAssets) {
+    if (totalAssets === 0)
+        return 0;
+    return (netIncome / totalAssets) * 100;
+}
+/**
+ * Calculate quick ratio (liquidity)
+ */
+export function calculateQuickRatio(currentAssets, inventory, currentLiabilities) {
+    if (currentLiabilities === 0)
+        return 0;
+    return (currentAssets - inventory) / currentLiabilities;
+}
+/**
+ * Calculate current ratio (liquidity)
+ */
+export function calculateCurrentRatio(currentAssets, currentLiabilities) {
+    if (currentLiabilities === 0)
+        return 0;
+    return currentAssets / currentLiabilities;
+}
+/**
+ * Calculate debt-to-equity ratio
+ */
+export function calculateDebtToEquity(totalDebt, totalEquity) {
+    if (totalEquity === 0)
+        return 0;
+    return totalDebt / totalEquity;
+}
+/**
+ * Format currency value
+ */
+export function formatCurrency(amount, currency = 'USD') {
+    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) {
+    const symbols = {
+        USD: '$',
+        EUR: '€',
+        GBP: '£',
+        JPY: '¥',
+        CNY: '¥',
+        CAD: 'C$',
+        AUD: 'A$',
+    };
+    return symbols[currency] || currency + ' ';
+}
+/**
+ * Create a financial statement
+ */
+export function createStatement(type, period, lineItems, currency = 'USD') {
+    return {
+        type,
+        period,
+        lineItems,
+        currency,
+    };
+}
+/**
+ * Get line item from financial statement
+ */
+export function getLineItem(statement, name) {
+    return statement.lineItems[name] || 0;
+}
+/**
+ * Compare financial metrics between periods
+ */
+export function compareMetrics(current, previous) {
+    const comparison = {};
+    const keys = [
+        'revenue',
+        'grossProfit',
+        'operatingIncome',
+        'netIncome',
+        'ebitda',
+    ];
+    for (const key of keys) {
+        const currentVal = current[key] || 0;
+        const previousVal = previous[key] || 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) {
+    const errors = [];
+    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.js

@@ -0,0 +1,214 @@
+/**
+ * Business goals definition and tracking
+ */
+/**
+ * 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) {
+    return definitions.map(goal => validateAndNormalizeGoal(goal));
+}
+/**
+ * Define a single goal
+ */
+export function Goal(definition) {
+    return validateAndNormalizeGoal(definition);
+}
+/**
+ * Validate and normalize a goal definition
+ */
+function validateAndNormalizeGoal(goal) {
+    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, progress) {
+    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) {
+    return {
+        ...goal,
+        status: 'at-risk',
+    };
+}
+/**
+ * Mark goal as completed
+ */
+export function complete(goal) {
+    return {
+        ...goal,
+        status: 'completed',
+        progress: 100,
+    };
+}
+/**
+ * Check if goal is overdue
+ */
+export function isOverdue(goal) {
+    if (!goal.targetDate)
+        return false;
+    return new Date() > goal.targetDate && goal.status !== 'completed';
+}
+/**
+ * Get goals by category
+ */
+export function getGoalsByCategory(goals, category) {
+    return goals.filter(g => g.category === category);
+}
+/**
+ * Get goals by status
+ */
+export function getGoalsByStatus(goals, status) {
+    return goals.filter(g => g.status === status);
+}
+/**
+ * Get goals by owner
+ */
+export function getGoalsByOwner(goals, owner) {
+    return goals.filter(g => g.owner === owner);
+}
+/**
+ * Calculate overall progress across all goals
+ */
+export function calculateOverallProgress(goals) {
+    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) {
+    const goalMap = new Map(goals.map(g => [g.name, g]));
+    function checkCircular(goalName, visited = new Set()) {
+        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) {
+    const goalMap = new Map(goals.map(g => [g.name, g]));
+    const sorted = [];
+    const visited = new Set();
+    function visit(goalName) {
+        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) {
+    const errors = [];
+    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,
+    };
+}

package/src/index.js

@@ -0,0 +1,131 @@
+/**
+ * business-as-code - Primitives for expressing business logic and processes as code
+ *
+ * This package provides primitives for defining business entities, goals, products,
+ * services, processes, workflows, KPIs, OKRs, and financial metrics.
+ *
+ * @example
+ * ```ts
+ * import { Business, Product, Goals, kpis, okrs, financials, $ } from 'business-as-code'
+ *
+ * // Define your business
+ * const company = Business({
+ *   name: 'Acme Corp',
+ *   mission: 'To make widgets accessible to everyone',
+ *   values: ['Innovation', 'Customer Focus', 'Integrity'],
+ * })
+ *
+ * // Define products
+ * const product = Product({
+ *   name: 'Widget Pro',
+ *   pricingModel: 'subscription',
+ *   price: 99,
+ *   cogs: 20,
+ * })
+ *
+ * // Define goals
+ * const goals = Goals([
+ *   {
+ *     name: 'Launch MVP',
+ *     category: 'strategic',
+ *     status: 'in-progress',
+ *     progress: 65,
+ *   },
+ * ])
+ *
+ * // Track KPIs
+ * const kpiList = kpis([
+ *   {
+ *     name: 'Monthly Recurring Revenue',
+ *     category: 'financial',
+ *     target: 100000,
+ *     current: 85000,
+ *   },
+ * ])
+ *
+ * // Define OKRs
+ * const okrList = okrs([
+ *   {
+ *     objective: 'Achieve Product-Market Fit',
+ *     keyResults: [
+ *       {
+ *         description: 'Increase NPS',
+ *         metric: 'NPS',
+ *         targetValue: 60,
+ *         currentValue: 52,
+ *       },
+ *     ],
+ *   },
+ * ])
+ *
+ * // Calculate financials
+ * const metrics = financials({
+ *   revenue: 1000000,
+ *   cogs: 300000,
+ *   operatingExpenses: 500000,
+ * })
+ *
+ * // Use $ helper for calculations
+ * console.log($.format(1234.56)) // "$1,234.56"
+ * console.log($.growth(120, 100)) // 20
+ * console.log($.margin(100, 60)) // 40
+ * ```
+ *
+ * @packageDocumentation
+ */
+// Export business entity functions
+export { Business, getTotalBudget, getTotalTeamSize, getDepartment, getTeam, validateBusiness, } from './business.js';
+// Export vision functions
+export { Vision, checkIndicator, calculateProgress, validateVision, } from './vision.js';
+// Export goal functions
+export { Goals, Goal, updateProgress, markAtRisk, complete, isOverdue, getGoalsByCategory, getGoalsByStatus, getGoalsByOwner, calculateOverallProgress, hasCircularDependencies, sortByDependencies, validateGoals, } from './goals.js';
+// Export product functions
+export { Product, calculateGrossMargin, calculateGrossProfit, getRoadmapByStatus, getRoadmapByPriority, getOverdueRoadmapItems, updateRoadmapItem, addFeature, removeFeature, validateProduct, } from './product.js';
+// Export service functions
+export { Service, calculateHourlyPrice, calculateMonthlyRetainer, checkSLAUptime, parseDeliveryTimeToDays, estimateCompletionDate, calculateValueBasedPrice, validateService, } from './service.js';
+// Export process functions
+export { Process, getStepsInOrder, getStepsByAutomationLevel, calculateTotalDuration, formatDuration, calculateAutomationPercentage, getMetric, meetsTarget, calculateMetricAchievement, updateMetric, addStep, removeStep, validateProcess, } from './process.js';
+// Export workflow functions
+export { Workflow, getActionsInOrder, getActionsByType, getConditionalActions, addAction, removeAction, updateAction, isEventTrigger, isScheduleTrigger, isWebhookTrigger, parseWaitDuration, evaluateCondition, fillTemplate, validateWorkflow, } from './workflow.js';
+// Export KPI functions
+export { kpis, kpi, calculateAchievement, meetsTarget as kpiMeetsTarget, updateCurrent, updateTarget, getKPIsByCategory, getKPIsByFrequency, getKPIsOnTarget, getKPIsOffTarget, calculateHealthScore, groupByCategory, calculateVariance, calculateVariancePercentage, formatValue, comparePerformance, validateKPIs, } from './kpis.js';
+// Export OKR functions
+export { okrs, okr, calculateKeyResultProgress, calculateOKRProgress, calculateConfidence, updateKeyResult, isKeyResultOnTrack, isOKROnTrack, getKeyResultsOnTrack, getKeyResultsAtRisk, getOKRsByOwner, getOKRsByPeriod, getOKRsByStatus, calculateSuccessRate, formatKeyResult, compareOKRPerformance, validateOKRs, } from './okrs.js';
+// Export financial functions
+export { financials, calculateGrossMargin as calculateFinancialGrossMargin, calculateOperatingMargin, calculateNetMargin, calculateEBITDAMargin, calculateBurnRate, calculateRunway, calculateCAC, calculateLTV, calculateLTVtoCAC, calculatePaybackPeriod, calculateARR, calculateMRR, calculateGrowthRate, calculateCAGR, calculateROI, calculateROE, calculateROA, calculateQuickRatio, calculateCurrentRatio, calculateDebtToEquity, formatCurrency, createStatement, getLineItem, compareMetrics, validateFinancials, } from './financials.js';
+// Export $ helper and context management
+export { $, createBusinessOperations, updateContext, getContext, resetContext, } from './dollar.js';
+export { 
+// SaaS Metric Calculation functions (produce structured SaaS metric objects)
+calculateMRR as calculateMRRMetric, calculateARRFromMRR as calculateARRMetric, calculateNRR as calculateNRRMetric, calculateGRR as calculateGRRMetric, calculateCACMetric, calculateLTVMetric, calculateLTVtoCACRatio, calculateQuickRatioMetric, calculateMagicNumberMetric, calculateBurnMultipleMetric, calculateRuleOf40Metric, calculateGrowthRates, calculateChurnMetrics, 
+// Time-series aggregation
+aggregateTimeSeries, createMetricPeriod, } from './metrics.js';
+export { 
+// Standard definitions
+StandardDimensions, StandardMeasures, CalculatedMetrics, 
+// Builders
+query, QueryBuilder, view, ViewBuilder, dashboard, DashboardBuilder, 
+// Pre-built queries
+MrrOverview, ArrBySegment, CohortRetention, UnitEconomics, RevenueByChannel, GrowthMetrics, 
+// Pre-built dashboards
+ExecutiveDashboard, } from './queries.js';
+export { StandardBusinessRoles, createBusinessRole, hasPermission, canHandleTask, canApproveRequest, canDelegateTask, findRoleForTask, createTaskAssignment, transitionTaskStatus, } from './roles.js';
+export { resolvePermissions, getApprovalChainForRequest, findManager, } from './organization.js';
+// =============================================================================
+// Entity Definitions (Noun pattern with Properties, Actions, Events)
+// =============================================================================
+export { 
+// Business
+Business as BusinessEntity, Vision as VisionEntity, Value as ValueEntity, BusinessEntities, BusinessCategories, 
+// Organization
+Organization as OrganizationEntity, Department as DepartmentEntity, Team as TeamEntity, Position as PositionEntity, Role as RoleEntity, Worker as WorkerEntity, OrganizationEntities, OrganizationCategories, 
+// Goals
+Goal as GoalEntity, OKR as OKREntity, KeyResult as KeyResultEntity, KPI as KPIEntity, Metric as MetricEntity, Initiative as InitiativeEntity, GoalEntities, GoalCategories, 
+// Offerings
+Product as ProductEntity, Service as ServiceEntity, Feature as FeatureEntity, PricingPlan as PricingPlanEntity, RoadmapItem as RoadmapItemEntity, OfferingEntities, OfferingCategories, 
+// Operations
+Process as ProcessEntity, ProcessStep as ProcessStepEntity, Workflow as WorkflowEntity, WorkflowAction as WorkflowActionEntity, WorkflowRun as WorkflowRunEntity, Policy as PolicyEntity, OperationsEntities, OperationsCategories, 
+// Financials
+Budget as BudgetEntity, Revenue as RevenueEntity, Expense as ExpenseEntity, Investment as InvestmentEntity, FinancialPeriod as FinancialPeriodEntity, Forecast as ForecastEntity, FinancialEntities, FinancialCategories, 
+// All
+AllBusinessEntities, BusinessEntityCategories, Entities, } from './entities/index.js';