business-as-code 2.0.1 → 2.1.1

package/src/metrics.js

@@ -0,0 +1,324 @@
+/**
+ * Standardized SaaS Metrics
+ *
+ * First-class types for common SaaS/subscription business metrics
+ * with auto-calculation over time periods.
+ *
+ * @packageDocumentation
+ */
+// =============================================================================
+// Calculation Functions
+// =============================================================================
+/**
+ * Calculate MRR from components
+ */
+export function calculateMRR(input) {
+    const reactivationMRR = input.reactivationMRR || 0;
+    const netNewMRR = input.newMRR + input.expansionMRR - input.contractionMRR - input.churnedMRR + reactivationMRR;
+    const total = input.previousMRR + netNewMRR;
+    return {
+        total,
+        newMRR: input.newMRR,
+        expansionMRR: input.expansionMRR,
+        contractionMRR: input.contractionMRR,
+        churnedMRR: input.churnedMRR,
+        reactivationMRR,
+        netNewMRR,
+        currency: input.currency || 'USD',
+        period: input.period,
+    };
+}
+/**
+ * Calculate ARR from MRR
+ */
+export function calculateARRFromMRR(mrr, currency = 'USD') {
+    return {
+        total: mrr * 12,
+        fromMRR: mrr * 12,
+        currency,
+        asOf: new Date(),
+    };
+}
+/**
+ * Calculate NRR
+ */
+export function calculateNRR(input) {
+    const endingMRR = input.startingMRR + input.expansion - input.contraction - input.churn;
+    const rate = input.startingMRR > 0 ? (endingMRR / input.startingMRR) * 100 : 0;
+    return {
+        rate,
+        startingMRR: input.startingMRR,
+        endingMRR,
+        expansion: input.expansion,
+        contraction: input.contraction,
+        churn: input.churn,
+        period: input.period,
+    };
+}
+/**
+ * Calculate GRR
+ */
+export function calculateGRR(input) {
+    const endingMRR = input.startingMRR - input.contraction - input.churn;
+    const rate = input.startingMRR > 0 ? Math.min((endingMRR / input.startingMRR) * 100, 100) : 0;
+    return {
+        rate,
+        startingMRR: input.startingMRR,
+        endingMRR,
+        contraction: input.contraction,
+        churn: input.churn,
+        period: input.period,
+    };
+}
+/**
+ * Calculate CAC
+ */
+export function calculateCACMetric(input) {
+    const value = input.newCustomers > 0 ? input.salesMarketingSpend / input.newCustomers : 0;
+    let byChannel;
+    if (input.byChannel) {
+        byChannel = {};
+        for (const [channel, data] of Object.entries(input.byChannel)) {
+            byChannel[channel] = data.customers > 0 ? data.spend / data.customers : 0;
+        }
+    }
+    return {
+        value,
+        totalSalesMarketingSpend: input.salesMarketingSpend,
+        newCustomersAcquired: input.newCustomers,
+        currency: input.currency || 'USD',
+        period: input.period,
+        byChannel,
+    };
+}
+/**
+ * Calculate LTV
+ */
+export function calculateLTVMetric(input) {
+    // LTV = (ARPU * Gross Margin) / Churn Rate
+    const averageLifetimeMonths = input.churnRate > 0 ? 1 / input.churnRate : 0;
+    const value = input.churnRate > 0 ? (input.arpu * input.grossMargin / 100) / input.churnRate : 0;
+    return {
+        value,
+        arpu: input.arpu,
+        grossMargin: input.grossMargin,
+        churnRate: input.churnRate,
+        averageLifetimeMonths,
+        currency: input.currency || 'USD',
+    };
+}
+/**
+ * Calculate LTV:CAC ratio
+ */
+export function calculateLTVtoCACRatio(ltv, cac) {
+    const ratio = cac.value > 0 ? ltv.value / cac.value : 0;
+    const paybackMonths = ltv.arpu > 0 && ltv.grossMargin > 0
+        ? cac.value / (ltv.arpu * ltv.grossMargin / 100)
+        : 0;
+    return {
+        ratio,
+        ltv: ltv.value,
+        cac: cac.value,
+        paybackMonths,
+        healthy: ratio >= 3,
+    };
+}
+/**
+ * Calculate Quick Ratio
+ */
+export function calculateQuickRatioMetric(mrr) {
+    const growth = mrr.newMRR + mrr.expansionMRR;
+    const loss = mrr.churnedMRR + mrr.contractionMRR;
+    const ratio = loss > 0 ? growth / loss : growth > 0 ? Infinity : 0;
+    return {
+        ratio,
+        newMRR: mrr.newMRR,
+        expansionMRR: mrr.expansionMRR,
+        churnedMRR: mrr.churnedMRR,
+        contractionMRR: mrr.contractionMRR,
+        healthy: ratio >= 4,
+        period: mrr.period,
+    };
+}
+/**
+ * Calculate Magic Number
+ */
+export function calculateMagicNumberMetric(input) {
+    const value = input.salesMarketingSpend > 0 ? input.netNewARR / input.salesMarketingSpend : 0;
+    return {
+        value,
+        netNewARR: input.netNewARR,
+        salesMarketingSpend: input.salesMarketingSpend,
+        efficient: value >= 0.75,
+        period: input.period,
+    };
+}
+/**
+ * Calculate Burn Multiple
+ */
+export function calculateBurnMultipleMetric(input) {
+    const value = input.netNewARR > 0 ? input.netBurn / input.netNewARR : Infinity;
+    return {
+        value,
+        netBurn: input.netBurn,
+        netNewARR: input.netNewARR,
+        efficient: value <= 1.5,
+        period: input.period,
+    };
+}
+/**
+ * Calculate Rule of 40
+ */
+export function calculateRuleOf40Metric(input) {
+    const score = input.revenueGrowthRate + input.profitMargin;
+    return {
+        score,
+        revenueGrowthRate: input.revenueGrowthRate,
+        profitMargin: input.profitMargin,
+        passing: score >= 40,
+        period: input.period,
+    };
+}
+/**
+ * Calculate growth rates
+ */
+export function calculateGrowthRates(input) {
+    const mom = input.previousMonth && input.previousMonth > 0
+        ? ((input.current - input.previousMonth) / input.previousMonth) * 100
+        : 0;
+    const qoq = input.previousQuarter && input.previousQuarter > 0
+        ? ((input.current - input.previousQuarter) / input.previousQuarter) * 100
+        : 0;
+    const yoy = input.previousYear && input.previousYear > 0
+        ? ((input.current - input.previousYear) / input.previousYear) * 100
+        : 0;
+    return {
+        mom,
+        qoq,
+        yoy,
+        metric: input.metric,
+        period: input.period,
+    };
+}
+/**
+ * Calculate churn metrics
+ */
+export function calculateChurnMetrics(input) {
+    const customerChurnRate = input.customersStart > 0
+        ? (input.customersLost / input.customersStart) * 100
+        : 0;
+    const revenueChurnRate = input.mrrStart > 0
+        ? (input.mrrChurned / input.mrrStart) * 100
+        : 0;
+    const netRevenueChurnRate = input.mrrStart > 0
+        ? ((input.mrrChurned - input.expansionMRR) / input.mrrStart) * 100
+        : 0;
+    return {
+        customerChurnRate,
+        customersLost: input.customersLost,
+        customersStart: input.customersStart,
+        revenueChurnRate,
+        mrrChurned: input.mrrChurned,
+        netRevenueChurnRate,
+        period: input.period,
+    };
+}
+// =============================================================================
+// Aggregation Functions
+// =============================================================================
+/**
+ * Aggregate time series data by period
+ */
+export function aggregateTimeSeries(series, targetPeriod) {
+    const buckets = new Map();
+    for (const point of series.dataPoints) {
+        const key = getBucketKey(point.timestamp, targetPeriod);
+        const existing = buckets.get(key) || [];
+        buckets.set(key, [...existing, point]);
+    }
+    const aggregatedPoints = [];
+    const aggregation = series.aggregation || 'sum';
+    for (const [key, points] of buckets) {
+        const values = points.map(p => p.value);
+        let aggregatedValue;
+        switch (aggregation) {
+            case 'sum':
+                aggregatedValue = values.reduce((a, b) => a + b, 0);
+                break;
+            case 'avg':
+                aggregatedValue = values.reduce((a, b) => a + b, 0) / values.length;
+                break;
+            case 'min':
+                aggregatedValue = Math.min(...values);
+                break;
+            case 'max':
+                aggregatedValue = Math.max(...values);
+                break;
+            case 'last':
+                aggregatedValue = values[values.length - 1] ?? 0;
+                break;
+            case 'first':
+                aggregatedValue = values[0] ?? 0;
+                break;
+            default:
+                aggregatedValue = values.reduce((a, b) => a + b, 0);
+        }
+        aggregatedPoints.push({
+            timestamp: new Date(key),
+            value: aggregatedValue,
+        });
+    }
+    return {
+        ...series,
+        dataPoints: aggregatedPoints.sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime()),
+    };
+}
+/**
+ * Get bucket key for time aggregation
+ */
+function getBucketKey(date, period) {
+    switch (period) {
+        case 'daily':
+            return date.toISOString().split('T')[0] || date.toISOString();
+        case 'weekly':
+            const weekStart = new Date(date);
+            weekStart.setDate(date.getDate() - date.getDay());
+            return weekStart.toISOString().split('T')[0] || weekStart.toISOString();
+        case 'monthly':
+            return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-01`;
+        case 'quarterly':
+            const quarter = Math.floor(date.getMonth() / 3);
+            return `${date.getFullYear()}-Q${quarter + 1}`;
+        case 'yearly':
+            return `${date.getFullYear()}-01-01`;
+        default:
+            return date.toISOString();
+    }
+}
+/**
+ * Create metric period from dates
+ */
+export function createMetricPeriod(period, start, end, label) {
+    return {
+        period,
+        range: { start, end },
+        label: label || formatPeriodLabel(period, start, end),
+    };
+}
+/**
+ * Format period label
+ */
+function formatPeriodLabel(period, start, end) {
+    const monthNames = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+    switch (period) {
+        case 'monthly':
+            return `${monthNames[start.getMonth()]} ${start.getFullYear()}`;
+        case 'quarterly':
+            const quarter = Math.floor(start.getMonth() / 3) + 1;
+            return `Q${quarter} ${start.getFullYear()}`;
+        case 'yearly':
+            return `${start.getFullYear()}`;
+        default:
+            return `${start.toLocaleDateString()} - ${end.toLocaleDateString()}`;
+    }
+}

package/src/okrs.js

@@ -0,0 +1,268 @@
+/**
+ * Objectives and Key Results (OKRs) management
+ */
+/**
+ * Define Objectives and Key Results for goal tracking
+ *
+ * @example
+ * ```ts
+ * const quarterlyOKRs = okrs([
+ *   {
+ *     objective: 'Achieve Product-Market Fit',
+ *     description: 'Validate that our product solves a real problem for customers',
+ *     period: 'Q2 2024',
+ *     owner: 'CEO',
+ *     keyResults: [
+ *       {
+ *         description: 'Increase Net Promoter Score',
+ *         metric: 'NPS',
+ *         startValue: 40,
+ *         targetValue: 60,
+ *         currentValue: 52,
+ *         unit: 'score',
+ *         progress: 60,
+ *       },
+ *       {
+ *         description: 'Reduce monthly churn rate',
+ *         metric: 'Churn Rate',
+ *         startValue: 8,
+ *         targetValue: 4,
+ *         currentValue: 5.5,
+ *         unit: 'percent',
+ *         progress: 62.5,
+ *       },
+ *       {
+ *         description: 'Achieve customer retention',
+ *         metric: 'Customers with 3+ months',
+ *         startValue: 50,
+ *         targetValue: 200,
+ *         currentValue: 125,
+ *         unit: 'customers',
+ *         progress: 50,
+ *       },
+ *     ],
+ *     status: 'on-track',
+ *     confidence: 75,
+ *   },
+ * ])
+ * ```
+ */
+export function okrs(definitions) {
+    return definitions.map(okr => validateAndNormalizeOKR(okr));
+}
+/**
+ * Define a single OKR
+ */
+export function okr(definition) {
+    return validateAndNormalizeOKR(definition);
+}
+/**
+ * Validate and normalize an OKR definition
+ */
+function validateAndNormalizeOKR(okr) {
+    if (!okr.objective) {
+        throw new Error('OKR objective is required');
+    }
+    // Calculate progress for key results if not set
+    const keyResults = okr.keyResults?.map(kr => ({
+        ...kr,
+        progress: kr.progress ?? calculateKeyResultProgress(kr),
+    }));
+    return {
+        ...okr,
+        keyResults,
+        status: okr.status || 'not-started',
+        confidence: okr.confidence ?? calculateConfidence(keyResults || []),
+        metadata: okr.metadata || {},
+    };
+}
+/**
+ * Calculate key result progress
+ */
+export function calculateKeyResultProgress(kr) {
+    if (kr.currentValue === undefined || kr.startValue === undefined)
+        return 0;
+    const total = kr.targetValue - kr.startValue;
+    if (total === 0)
+        return 100;
+    const current = kr.currentValue - kr.startValue;
+    const progress = (current / total) * 100;
+    return Math.max(0, Math.min(100, progress));
+}
+/**
+ * Calculate overall OKR progress
+ */
+export function calculateOKRProgress(okr) {
+    if (!okr.keyResults || okr.keyResults.length === 0)
+        return 0;
+    const totalProgress = okr.keyResults.reduce((sum, kr) => {
+        return sum + (kr.progress ?? calculateKeyResultProgress(kr));
+    }, 0);
+    return totalProgress / okr.keyResults.length;
+}
+/**
+ * Calculate confidence score based on key results
+ */
+export function calculateConfidence(keyResults) {
+    if (keyResults.length === 0)
+        return 0;
+    const totalProgress = keyResults.reduce((sum, kr) => {
+        return sum + (kr.progress ?? calculateKeyResultProgress(kr));
+    }, 0);
+    const avgProgress = totalProgress / keyResults.length;
+    // Confidence tends to be slightly lower than actual progress
+    return Math.max(0, Math.min(100, avgProgress - 10));
+}
+/**
+ * Update key result current value
+ */
+export function updateKeyResult(okr, krDescription, currentValue) {
+    const keyResults = okr.keyResults?.map(kr => {
+        if (kr.description === krDescription) {
+            const updatedKR = { ...kr, currentValue };
+            return {
+                ...updatedKR,
+                progress: calculateKeyResultProgress(updatedKR),
+            };
+        }
+        return kr;
+    });
+    // Recalculate overall status and confidence
+    const progress = calculateOKRProgress({ ...okr, keyResults });
+    const status = determineOKRStatus(progress, okr.confidence || 0);
+    return {
+        ...okr,
+        keyResults,
+        status,
+        confidence: calculateConfidence(keyResults || []),
+    };
+}
+/**
+ * Determine OKR status based on progress and confidence
+ */
+function determineOKRStatus(progress, confidence) {
+    if (progress === 0)
+        return 'not-started';
+    if (progress === 100)
+        return 'completed';
+    if (confidence < 50 || progress < 30)
+        return 'at-risk';
+    return 'on-track';
+}
+/**
+ * Check if key result is on track
+ */
+export function isKeyResultOnTrack(kr) {
+    const progress = kr.progress ?? calculateKeyResultProgress(kr);
+    return progress >= 70;
+}
+/**
+ * Check if OKR is on track
+ */
+export function isOKROnTrack(okr) {
+    const progress = calculateOKRProgress(okr);
+    return progress >= 70 && (okr.confidence ?? 0) >= 60;
+}
+/**
+ * Get key results that are on track
+ */
+export function getKeyResultsOnTrack(okr) {
+    return okr.keyResults?.filter(isKeyResultOnTrack) || [];
+}
+/**
+ * Get key results that are at risk
+ */
+export function getKeyResultsAtRisk(okr) {
+    return okr.keyResults?.filter(kr => !isKeyResultOnTrack(kr)) || [];
+}
+/**
+ * Get OKRs by owner
+ */
+export function getOKRsByOwner(okrs, owner) {
+    return okrs.filter(okr => okr.owner === owner);
+}
+/**
+ * Get OKRs by period
+ */
+export function getOKRsByPeriod(okrs, period) {
+    return okrs.filter(okr => okr.period === period);
+}
+/**
+ * Get OKRs by status
+ */
+export function getOKRsByStatus(okrs, status) {
+    return okrs.filter(okr => okr.status === status);
+}
+/**
+ * Calculate success rate across all OKRs
+ */
+export function calculateSuccessRate(okrs) {
+    if (okrs.length === 0)
+        return 0;
+    const avgProgress = okrs.reduce((sum, okr) => {
+        return sum + calculateOKRProgress(okr);
+    }, 0) / okrs.length;
+    return avgProgress;
+}
+/**
+ * Format key result for display
+ */
+export function formatKeyResult(kr) {
+    const progress = kr.progress ?? calculateKeyResultProgress(kr);
+    const current = kr.currentValue ?? kr.startValue ?? 0;
+    const target = kr.targetValue;
+    return `${kr.description}: ${current}/${target} ${kr.unit || ''} (${progress.toFixed(0)}%)`;
+}
+/**
+ * Compare OKR performance between periods
+ */
+export function compareOKRPerformance(current, previous) {
+    const currentProgress = calculateOKRProgress(current);
+    const previousProgress = calculateOKRProgress(previous);
+    const progressDelta = currentProgress - previousProgress;
+    const currentConfidence = current.confidence ?? 0;
+    const previousConfidence = previous.confidence ?? 0;
+    const confidenceDelta = currentConfidence - previousConfidence;
+    const improved = progressDelta > 0 && confidenceDelta >= 0;
+    return { progressDelta, confidenceDelta, improved };
+}
+/**
+ * Validate OKR definitions
+ */
+export function validateOKRs(okrs) {
+    const errors = [];
+    for (const okr of okrs) {
+        if (!okr.objective) {
+            errors.push('OKR objective is required');
+        }
+        if (okr.objective && okr.objective.length < 10) {
+            errors.push(`OKR objective "${okr.objective}" should be at least 10 characters`);
+        }
+        if (okr.confidence !== undefined && (okr.confidence < 0 || okr.confidence > 100)) {
+            errors.push(`OKR "${okr.objective}" confidence must be between 0 and 100`);
+        }
+        if (okr.keyResults) {
+            if (okr.keyResults.length === 0) {
+                errors.push(`OKR "${okr.objective}" must have at least one key result`);
+            }
+            if (okr.keyResults.length > 5) {
+                errors.push(`OKR "${okr.objective}" should have no more than 5 key results`);
+            }
+            for (const kr of okr.keyResults) {
+                if (!kr.description) {
+                    errors.push(`Key result in OKR "${okr.objective}" must have a description`);
+                }
+                if (!kr.metric) {
+                    errors.push(`Key result "${kr.description}" must have a metric`);
+                }
+                if (kr.progress !== undefined && (kr.progress < 0 || kr.progress > 100)) {
+                    errors.push(`Key result "${kr.description}" progress must be between 0 and 100`);
+                }
+            }
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}