@dotdo/do 0.1.0

package/dist/do/business/financial/metrics.d.ts

@@ -0,0 +1,370 @@
+/**
+ * Financial Metrics
+ *
+ * Calculates SaaS and revenue metrics:
+ * - MRR/ARR tracking and movements
+ * - Customer metrics and churn
+ * - Unit economics (LTV, CAC, payback)
+ *
+ * @module financial/metrics
+ */
+import type { ReportPeriod, MRRMetrics, CustomerMetrics, Subscription, SubscriptionStatus } from '../../../types/financial';
+import type { DigitalObjectRef } from '../../../types/identity';
+/**
+ * Configuration for metrics calculator
+ */
+export interface MetricsCalculatorConfig {
+    /** Default currency */
+    defaultCurrency?: string;
+    /** Active subscription statuses */
+    activeStatuses?: SubscriptionStatus[];
+    /** Trial statuses (excluded from MRR) */
+    trialStatuses?: SubscriptionStatus[];
+}
+/**
+ * Detailed MRR movement breakdown
+ */
+export interface MRRMovement {
+    /** Movement type */
+    type: 'new' | 'expansion' | 'contraction' | 'churn' | 'reactivation';
+    /** Customer reference */
+    customerRef: DigitalObjectRef;
+    /** Subscription ID */
+    subscriptionId: string;
+    /** Previous MRR (0 for new) */
+    previousMRR: number;
+    /** New MRR (0 for churn) */
+    newMRR: number;
+    /** MRR change amount */
+    change: number;
+    /** Movement date */
+    date: number;
+    /** Movement reason */
+    reason?: string;
+}
+/**
+ * Customer cohort for analysis
+ */
+export interface CustomerCohort {
+    /** Cohort identifier (e.g., "2024-01") */
+    cohortId: string;
+    /** Cohort start date */
+    startDate: number;
+    /** Number of customers in cohort */
+    customerCount: number;
+    /** Initial MRR */
+    initialMRR: number;
+    /** Retention by month */
+    retention: Array<{
+        month: number;
+        customersRemaining: number;
+        mrrRemaining: number;
+        retentionRate: number;
+        revenueRetentionRate: number;
+    }>;
+}
+/**
+ * Revenue per customer analysis
+ */
+export interface RevenueAnalysis {
+    /** Period */
+    period: ReportPeriod;
+    /** Average revenue per user */
+    arpu: number;
+    /** Average revenue per paying user */
+    arppu: number;
+    /** Revenue by plan tier */
+    byTier: Array<{
+        tierId: string;
+        tierName: string;
+        customerCount: number;
+        mrr: number;
+        percentage: number;
+    }>;
+    /** Revenue concentration */
+    concentration: {
+        top10Percent: number;
+        top20Percent: number;
+    };
+}
+/**
+ * Unit economics metrics
+ */
+export interface UnitEconomics {
+    /** Period */
+    period: ReportPeriod;
+    /** Customer lifetime value */
+    ltv: number;
+    /** Customer acquisition cost */
+    cac: number;
+    /** LTV/CAC ratio */
+    ltvCacRatio: number;
+    /** CAC payback period (months) */
+    cacPaybackMonths: number;
+    /** Gross margin */
+    grossMargin: number;
+    /** Net revenue retention */
+    netRevenueRetention: number;
+}
+/**
+ * Subscription cohort analysis
+ */
+export interface CohortAnalysis {
+    /** Cohorts */
+    cohorts: CustomerCohort[];
+    /** Average retention by month */
+    averageRetention: Array<{
+        month: number;
+        customerRetention: number;
+        revenueRetention: number;
+    }>;
+}
+/**
+ * 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 declare class MetricsCalculator {
+    private readonly config;
+    /**
+     * Create a new MetricsCalculator instance
+     *
+     * @param config - Metrics calculator configuration
+     */
+    constructor(config?: MetricsCalculatorConfig);
+    /**
+     * 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)
+     * ```
+     */
+    getMRRMetrics(period: ReportPeriod, subscriptions: Subscription[]): Promise<MRRMetrics>;
+    /**
+     * Get detailed MRR movements for a period
+     *
+     * @param period - Report period
+     * @param subscriptions - List of subscriptions
+     * @returns List of MRR movements
+     */
+    getMRRMovements(period: ReportPeriod, subscriptions: Subscription[]): Promise<MRRMovement[]>;
+    /**
+     * 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: Subscription, priceAmount: number, interval: 'month' | 'year'): number;
+    /**
+     * Calculate ARR from MRR
+     *
+     * @param mrr - Monthly recurring revenue
+     * @returns Annual recurring revenue
+     */
+    calculateARR(mrr: number): number;
+    /**
+     * Get MRR trend over time
+     *
+     * @param periods - List of periods to analyze
+     * @param subscriptions - List of subscriptions
+     * @returns MRR metrics for each period
+     */
+    getMRRTrend(periods: ReportPeriod[], subscriptions: Subscription[]): Promise<MRRMetrics[]>;
+    /**
+     * 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)
+     * ```
+     */
+    getCustomerMetrics(period: ReportPeriod, subscriptions: Subscription[]): Promise<CustomerMetrics>;
+    /**
+     * 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: number, startingCustomers: number): number;
+    /**
+     * Calculate revenue churn rate
+     *
+     * @param churnedMRR - MRR lost to churn
+     * @param startingMRR - MRR at period start
+     * @returns Revenue churn rate as percentage
+     */
+    calculateRevenueChurnRate(churnedMRR: number, startingMRR: number): number;
+    /**
+     * Calculate net revenue retention
+     *
+     * @param metrics - MRR metrics
+     * @returns Net revenue retention as percentage
+     */
+    calculateNetRevenueRetention(metrics: MRRMetrics): number;
+    /**
+     * Calculate gross revenue retention
+     *
+     * @param metrics - MRR metrics
+     * @returns Gross revenue retention as percentage
+     */
+    calculateGrossRevenueRetention(metrics: MRRMetrics): number;
+    /**
+     * 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
+     */
+    getUnitEconomics(period: ReportPeriod, subscriptions: Subscription[], marketingSpend: number, cogs: number): Promise<UnitEconomics>;
+    /**
+     * 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: number, grossMargin: number, monthlyChurnRate: number): number;
+    /**
+     * Calculate customer acquisition cost
+     *
+     * @param marketingSpend - Total marketing spend
+     * @param newCustomers - Number of new customers acquired
+     * @returns Customer acquisition cost
+     */
+    calculateCAC(marketingSpend: number, newCustomers: number): number;
+    /**
+     * 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: number, arpu: number, grossMargin: number): number;
+    /**
+     * Calculate Quick Ratio
+     *
+     * Measures growth efficiency: (New + Expansion + Reactivation) / (Churn + Contraction)
+     *
+     * @param metrics - MRR metrics
+     * @returns Quick ratio
+     */
+    calculateQuickRatio(metrics: MRRMetrics): number;
+    /**
+     * 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
+     */
+    getCohortAnalysis(subscriptions: Subscription[], numberOfCohorts?: number): Promise<CohortAnalysis>;
+    /**
+     * Get retention curve for a cohort
+     *
+     * @param cohortId - Cohort identifier
+     * @param subscriptions - List of subscriptions
+     * @returns Customer cohort with retention data
+     */
+    getCohortRetention(cohortId: string, subscriptions: Subscription[]): Promise<CustomerCohort>;
+    /**
+     * Analyze revenue distribution
+     *
+     * @param period - Report period
+     * @param subscriptions - List of subscriptions
+     * @returns Revenue analysis
+     */
+    getRevenueAnalysis(period: ReportPeriod, subscriptions: Subscription[]): Promise<RevenueAnalysis>;
+    /**
+     * Calculate ARPU (Average Revenue Per User)
+     *
+     * @param totalMRR - Total MRR
+     * @param totalCustomers - Total number of customers
+     * @returns ARPU
+     */
+    calculateARPU(totalMRR: number, totalCustomers: number): number;
+    /**
+     * 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: number, growthRate: number, months: number): number[];
+    /**
+     * 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: number, targetMRR: number, growthRate: number): number;
+}
+/**
+ * Metrics error codes
+ */
+export declare const MetricsErrorCodes: {
+    readonly INVALID_PERIOD: "INVALID_PERIOD";
+    readonly NO_DATA: "NO_DATA";
+    readonly CALCULATION_ERROR: "CALCULATION_ERROR";
+};
+export type MetricsErrorCode = typeof MetricsErrorCodes[keyof typeof MetricsErrorCodes];
+/**
+ * Metrics error
+ */
+export declare class MetricsError extends Error {
+    readonly code: MetricsErrorCode;
+    readonly details?: unknown | undefined;
+    constructor(code: MetricsErrorCode, message: string, details?: unknown | undefined);
+}
+//# sourceMappingURL=metrics.d.ts.map

package/dist/do/business/financial/metrics.d.ts.map

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