@dotdo/do 0.1.0

package/dist/do/business/financial/metrics.js

@@ -0,0 +1,376 @@
+/**
+ * Financial Metrics
+ *
+ * Calculates SaaS and revenue metrics:
+ * - MRR/ARR tracking and movements
+ * - Customer metrics and churn
+ * - Unit economics (LTV, CAC, payback)
+ *
+ * @module financial/metrics
+ */
+/**
+ * Metrics calculator for Digital Objects
+ *
+ * Calculates SaaS revenue metrics including MRR, churn,
+ * and customer lifetime value.
+ *
+ * @example
+ * ```typescript
+ * const metrics = new MetricsCalculator()
+ *
+ * // Get MRR metrics for last month
+ * const mrr = await metrics.getMRRMetrics({
+ *   start: startOfMonth,
+ *   end: endOfMonth
+ * }, subscriptions)
+ *
+ * console.log('Ending MRR:', mrr.endingMRR)
+ * console.log('Net New MRR:', mrr.netNewMRR)
+ * console.log('Growth Rate:', mrr.growthRate, '%')
+ * ```
+ */
+export class MetricsCalculator {
+    config;
+    /**
+     * Create a new MetricsCalculator instance
+     *
+     * @param config - Metrics calculator configuration
+     */
+    constructor(config = {}) {
+        this.config = {
+            defaultCurrency: 'usd',
+            activeStatuses: ['Active', 'PastDue'],
+            trialStatuses: ['Trialing'],
+            ...config,
+        };
+    }
+    // =========================================================================
+    // MRR Metrics
+    // =========================================================================
+    /**
+     * Calculate MRR metrics for a period
+     *
+     * @param period - Report period
+     * @param subscriptions - List of subscriptions to analyze
+     * @returns MRR metrics
+     *
+     * @example
+     * ```typescript
+     * const mrr = await metrics.getMRRMetrics(period, subscriptions)
+     *
+     * // MRR breakdown
+     * console.log('New MRR:', mrr.newMRR)
+     * console.log('Expansion MRR:', mrr.expansionMRR)
+     * console.log('Contraction MRR:', mrr.contractionMRR)
+     * console.log('Churned MRR:', mrr.churnedMRR)
+     * ```
+     */
+    async getMRRMetrics(period, subscriptions) {
+        // TODO: Implement MRR calculation
+        throw new Error('Not implemented');
+    }
+    /**
+     * Get detailed MRR movements for a period
+     *
+     * @param period - Report period
+     * @param subscriptions - List of subscriptions
+     * @returns List of MRR movements
+     */
+    async getMRRMovements(period, subscriptions) {
+        // TODO: Implement MRR movement tracking
+        throw new Error('Not implemented');
+    }
+    /**
+     * Calculate MRR for a single subscription
+     *
+     * Normalizes annual plans to monthly equivalent.
+     *
+     * @param subscription - The subscription
+     * @param priceAmount - Price amount in smallest currency unit
+     * @param interval - Billing interval
+     * @returns Monthly recurring revenue
+     */
+    calculateSubscriptionMRR(subscription, priceAmount, interval) {
+        const quantity = subscription.quantity || 1;
+        if (interval === 'year') {
+            return Math.round((priceAmount * quantity) / 12);
+        }
+        return priceAmount * quantity;
+    }
+    /**
+     * Calculate ARR from MRR
+     *
+     * @param mrr - Monthly recurring revenue
+     * @returns Annual recurring revenue
+     */
+    calculateARR(mrr) {
+        return mrr * 12;
+    }
+    /**
+     * Get MRR trend over time
+     *
+     * @param periods - List of periods to analyze
+     * @param subscriptions - List of subscriptions
+     * @returns MRR metrics for each period
+     */
+    async getMRRTrend(periods, subscriptions) {
+        // TODO: Implement MRR trend calculation
+        throw new Error('Not implemented');
+    }
+    // =========================================================================
+    // Customer Metrics
+    // =========================================================================
+    /**
+     * Calculate customer metrics for a period
+     *
+     * @param period - Report period
+     * @param subscriptions - List of subscriptions
+     * @returns Customer metrics
+     *
+     * @example
+     * ```typescript
+     * const customers = await metrics.getCustomerMetrics(period, subscriptions)
+     *
+     * console.log('Total Customers:', customers.totalCustomers)
+     * console.log('Churn Rate:', customers.churnRate, '%')
+     * console.log('ARPC:', customers.arpc)
+     * ```
+     */
+    async getCustomerMetrics(period, subscriptions) {
+        // TODO: Implement customer metrics calculation
+        throw new Error('Not implemented');
+    }
+    /**
+     * Calculate customer churn rate
+     *
+     * @param churnedCustomers - Number of churned customers
+     * @param startingCustomers - Number of customers at period start
+     * @returns Churn rate as percentage
+     */
+    calculateChurnRate(churnedCustomers, startingCustomers) {
+        if (startingCustomers === 0)
+            return 0;
+        return (churnedCustomers / startingCustomers) * 100;
+    }
+    /**
+     * Calculate revenue churn rate
+     *
+     * @param churnedMRR - MRR lost to churn
+     * @param startingMRR - MRR at period start
+     * @returns Revenue churn rate as percentage
+     */
+    calculateRevenueChurnRate(churnedMRR, startingMRR) {
+        if (startingMRR === 0)
+            return 0;
+        return (churnedMRR / startingMRR) * 100;
+    }
+    /**
+     * Calculate net revenue retention
+     *
+     * @param metrics - MRR metrics
+     * @returns Net revenue retention as percentage
+     */
+    calculateNetRevenueRetention(metrics) {
+        if (metrics.startingMRR === 0)
+            return 100;
+        const retained = metrics.startingMRR + metrics.expansionMRR -
+            metrics.contractionMRR - metrics.churnedMRR;
+        return (retained / metrics.startingMRR) * 100;
+    }
+    /**
+     * Calculate gross revenue retention
+     *
+     * @param metrics - MRR metrics
+     * @returns Gross revenue retention as percentage
+     */
+    calculateGrossRevenueRetention(metrics) {
+        if (metrics.startingMRR === 0)
+            return 100;
+        const retained = metrics.startingMRR - metrics.contractionMRR - metrics.churnedMRR;
+        return (retained / metrics.startingMRR) * 100;
+    }
+    // =========================================================================
+    // Unit Economics
+    // =========================================================================
+    /**
+     * Calculate unit economics
+     *
+     * @param period - Report period
+     * @param subscriptions - List of subscriptions
+     * @param marketingSpend - Total marketing spend in period
+     * @param cogs - Cost of goods sold
+     * @returns Unit economics metrics
+     */
+    async getUnitEconomics(period, subscriptions, marketingSpend, cogs) {
+        // TODO: Implement unit economics calculation
+        throw new Error('Not implemented');
+    }
+    /**
+     * Calculate customer lifetime value
+     *
+     * Uses the formula: LTV = ARPU * Gross Margin / Churn Rate
+     *
+     * @param arpu - Average revenue per user (monthly)
+     * @param grossMargin - Gross margin percentage (0-100)
+     * @param monthlyChurnRate - Monthly churn rate percentage (0-100)
+     * @returns Customer lifetime value
+     */
+    calculateLTV(arpu, grossMargin, monthlyChurnRate) {
+        if (monthlyChurnRate === 0) {
+            // No churn = infinite LTV, cap at reasonable multiple
+            return arpu * (grossMargin / 100) * 120; // 10 year cap
+        }
+        return (arpu * (grossMargin / 100)) / (monthlyChurnRate / 100);
+    }
+    /**
+     * Calculate customer acquisition cost
+     *
+     * @param marketingSpend - Total marketing spend
+     * @param newCustomers - Number of new customers acquired
+     * @returns Customer acquisition cost
+     */
+    calculateCAC(marketingSpend, newCustomers) {
+        if (newCustomers === 0)
+            return 0;
+        return marketingSpend / newCustomers;
+    }
+    /**
+     * Calculate CAC payback period
+     *
+     * @param cac - Customer acquisition cost
+     * @param arpu - Average revenue per user (monthly)
+     * @param grossMargin - Gross margin percentage (0-100)
+     * @returns Payback period in months
+     */
+    calculateCACPayback(cac, arpu, grossMargin) {
+        const monthlyContribution = arpu * (grossMargin / 100);
+        if (monthlyContribution === 0)
+            return Infinity;
+        return cac / monthlyContribution;
+    }
+    /**
+     * Calculate Quick Ratio
+     *
+     * Measures growth efficiency: (New + Expansion + Reactivation) / (Churn + Contraction)
+     *
+     * @param metrics - MRR metrics
+     * @returns Quick ratio
+     */
+    calculateQuickRatio(metrics) {
+        const gains = metrics.newMRR + metrics.expansionMRR + metrics.reactivationMRR;
+        const losses = metrics.churnedMRR + metrics.contractionMRR;
+        if (losses === 0)
+            return Infinity;
+        return gains / losses;
+    }
+    // =========================================================================
+    // Cohort Analysis
+    // =========================================================================
+    /**
+     * Perform cohort analysis
+     *
+     * Groups customers by signup month and tracks retention over time.
+     *
+     * @param subscriptions - List of subscriptions
+     * @param numberOfCohorts - Number of monthly cohorts to analyze
+     * @returns Cohort analysis
+     */
+    async getCohortAnalysis(subscriptions, numberOfCohorts = 12) {
+        // TODO: Implement cohort analysis
+        throw new Error('Not implemented');
+    }
+    /**
+     * Get retention curve for a cohort
+     *
+     * @param cohortId - Cohort identifier
+     * @param subscriptions - List of subscriptions
+     * @returns Customer cohort with retention data
+     */
+    async getCohortRetention(cohortId, subscriptions) {
+        // TODO: Implement cohort retention calculation
+        throw new Error('Not implemented');
+    }
+    // =========================================================================
+    // Revenue Analysis
+    // =========================================================================
+    /**
+     * Analyze revenue distribution
+     *
+     * @param period - Report period
+     * @param subscriptions - List of subscriptions
+     * @returns Revenue analysis
+     */
+    async getRevenueAnalysis(period, subscriptions) {
+        // TODO: Implement revenue analysis
+        throw new Error('Not implemented');
+    }
+    /**
+     * Calculate ARPU (Average Revenue Per User)
+     *
+     * @param totalMRR - Total MRR
+     * @param totalCustomers - Total number of customers
+     * @returns ARPU
+     */
+    calculateARPU(totalMRR, totalCustomers) {
+        if (totalCustomers === 0)
+            return 0;
+        return totalMRR / totalCustomers;
+    }
+    // =========================================================================
+    // Forecasting
+    // =========================================================================
+    /**
+     * Forecast future MRR
+     *
+     * Simple linear forecast based on recent growth rate.
+     *
+     * @param currentMRR - Current MRR
+     * @param growthRate - Monthly growth rate percentage
+     * @param months - Number of months to forecast
+     * @returns Forecasted MRR for each month
+     */
+    forecastMRR(currentMRR, growthRate, months) {
+        const forecast = [];
+        let mrr = currentMRR;
+        for (let i = 0; i < months; i++) {
+            mrr = mrr * (1 + growthRate / 100);
+            forecast.push(Math.round(mrr));
+        }
+        return forecast;
+    }
+    /**
+     * Calculate time to target MRR
+     *
+     * @param currentMRR - Current MRR
+     * @param targetMRR - Target MRR
+     * @param growthRate - Monthly growth rate percentage
+     * @returns Number of months to reach target
+     */
+    calculateTimeToTarget(currentMRR, targetMRR, growthRate) {
+        if (growthRate <= 0 || currentMRR >= targetMRR)
+            return 0;
+        return Math.ceil(Math.log(targetMRR / currentMRR) / Math.log(1 + growthRate / 100));
+    }
+}
+/**
+ * Metrics error codes
+ */
+export const MetricsErrorCodes = {
+    INVALID_PERIOD: 'INVALID_PERIOD',
+    NO_DATA: 'NO_DATA',
+    CALCULATION_ERROR: 'CALCULATION_ERROR',
+};
+/**
+ * Metrics error
+ */
+export class MetricsError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'MetricsError';
+    }
+}
+//# sourceMappingURL=metrics.js.map

package/dist/do/business/financial/metrics.js.map

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