business-as-code 2.3.0 → 2.4.0

package/dist/metrics.js

@@ -0,0 +1,330 @@
+/**
+ * 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;
+    const result = {
+        value,
+        totalSalesMarketingSpend: input.salesMarketingSpend,
+        newCustomersAcquired: input.newCustomers,
+        currency: input.currency || 'USD',
+        period: input.period,
+    };
+    if (input.byChannel) {
+        const byChannel = {};
+        for (const [channel, data] of Object.entries(input.byChannel)) {
+            byChannel[channel] = data.customers > 0 ? data.spend / data.customers : 0;
+        }
+        result.byChannel = byChannel;
+    }
+    return result;
+}
+/**
+ * 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()}`;
+    }
+}
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"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"}

package/dist/okrs.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Objectives and Key Results (OKRs) management
+ *
+ * Uses org.ai OKR types for standardized OKR definitions across the ecosystem.
+ */
+import type { OKRDefinition, KeyResult } from './types.js';
+import type { OKR as OrgOKR, KeyResult as OrgKeyResult, OKRStatus, KeyResultStatus } from 'org.ai';
+export type { OrgOKR, OrgKeyResult, OKRStatus, KeyResultStatus };
+/**
+ * Convert a business-as-code KeyResult to an org.ai KeyResult
+ *
+ * @param kr - Business key result
+ * @param id - Optional identifier
+ * @returns org.ai KeyResult object
+ */
+export declare function toOrgKeyResult(kr: KeyResult, id?: string): OrgKeyResult;
+/**
+ * Convert an org.ai KeyResult to a business-as-code KeyResult
+ *
+ * @param kr - org.ai KeyResult object
+ * @returns Business key result
+ */
+export declare function fromOrgKeyResult(kr: OrgKeyResult): KeyResult;
+/**
+ * Convert a business-as-code OKRDefinition to an org.ai OKR
+ *
+ * @param definition - Business OKR definition
+ * @param id - Optional unique identifier
+ * @returns org.ai OKR object
+ */
+export declare function toOrgOKR(definition: OKRDefinition, id?: string): OrgOKR;
+/**
+ * Convert an org.ai OKR to a business-as-code OKRDefinition
+ *
+ * @param okr - org.ai OKR object
+ * @returns Business OKR definition
+ */
+export declare function fromOrgOKR(okr: OrgOKR): OKRDefinition;
+/**
+ * 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 declare function okrs(definitions: OKRDefinition[]): OKRDefinition[];
+/**
+ * Define a single OKR
+ */
+export declare function okr(definition: OKRDefinition): OKRDefinition;
+/**
+ * Calculate key result progress
+ */
+export declare function calculateKeyResultProgress(kr: KeyResult): number;
+/**
+ * Calculate overall OKR progress
+ */
+export declare function calculateOKRProgress(okr: OKRDefinition): number;
+/**
+ * Calculate confidence score based on key results
+ */
+export declare function calculateConfidence(keyResults: KeyResult[]): number;
+/**
+ * Update key result current value
+ */
+export declare function updateKeyResult(okr: OKRDefinition, krDescription: string, currentValue: number): OKRDefinition;
+/**
+ * Check if key result is on track
+ */
+export declare function isKeyResultOnTrack(kr: KeyResult): boolean;
+/**
+ * Check if OKR is on track
+ */
+export declare function isOKROnTrack(okr: OKRDefinition): boolean;
+/**
+ * Get key results that are on track
+ */
+export declare function getKeyResultsOnTrack(okr: OKRDefinition): KeyResult[];
+/**
+ * Get key results that are at risk
+ */
+export declare function getKeyResultsAtRisk(okr: OKRDefinition): KeyResult[];
+/**
+ * Get OKRs by owner
+ */
+export declare function getOKRsByOwner(okrs: OKRDefinition[], owner: string): OKRDefinition[];
+/**
+ * Get OKRs by period
+ */
+export declare function getOKRsByPeriod(okrs: OKRDefinition[], period: string): OKRDefinition[];
+/**
+ * Get OKRs by status
+ */
+export declare function getOKRsByStatus(okrs: OKRDefinition[], status: OKRDefinition['status']): OKRDefinition[];
+/**
+ * Calculate success rate across all OKRs
+ */
+export declare function calculateSuccessRate(okrs: OKRDefinition[]): number;
+/**
+ * Format key result for display
+ */
+export declare function formatKeyResult(kr: KeyResult): string;
+/**
+ * Compare OKR performance between periods
+ */
+export declare function compareOKRPerformance(current: OKRDefinition, previous: OKRDefinition): {
+    progressDelta: number;
+    confidenceDelta: number;
+    improved: boolean;
+};
+/**
+ * Validate OKR definitions
+ */
+export declare function validateOKRs(okrs: OKRDefinition[]): {
+    valid: boolean;
+    errors: string[];
+};
+//# sourceMappingURL=okrs.d.ts.map

package/dist/okrs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"okrs.d.ts","sourceRoot":"","sources":["../src/okrs.ts"],"names":[],"mappings":"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"}