business-as-code/dist/entities/financials.js

Primitives for expressing business logic and processes as code

/**
 * Financial Entity Types (Nouns)
 *
 * Financial entities: Budget, Revenue, Expense, Investment, FinancialPeriod.
 *
 * @packageDocumentation
 */
// =============================================================================
// Budget
// =============================================================================
/**
 * Budget entity
 *
 * Represents a budget allocation.
 */
export const Budget = {
    singular: 'budget',
    plural: 'budgets',
    description: 'A budget allocation',
    properties: {
        // Identity
        name: {
            type: 'string',
            description: 'Budget name',
        },
        description: {
            type: 'string',
            optional: true,
            description: 'Budget description',
        },
        // Classification
        type: {
            type: 'string',
            optional: true,
            description: 'Budget type',
            examples: ['operating', 'capital', 'project', 'marketing', 'hiring', 'r&d'],
        },
        category: {
            type: 'string',
            optional: true,
            description: 'Budget category',
        },
        // Period
        period: {
            type: 'string',
            optional: true,
            description: 'Budget period (e.g., "Q1 2025", "FY2025")',
        },
        startDate: {
            type: 'date',
            optional: true,
            description: 'Period start date',
        },
        endDate: {
            type: 'date',
            optional: true,
            description: 'Period end date',
        },
        // Amounts
        amount: {
            type: 'number',
            description: 'Budgeted amount',
        },
        currency: {
            type: 'string',
            optional: true,
            description: 'Currency code',
        },
        spent: {
            type: 'number',
            optional: true,
            description: 'Amount spent',
        },
        committed: {
            type: 'number',
            optional: true,
            description: 'Amount committed',
        },
        available: {
            type: 'number',
            optional: true,
            description: 'Available amount',
        },
        // Utilization
        utilization: {
            type: 'number',
            optional: true,
            description: 'Utilization percentage',
        },
        // Status
        status: {
            type: 'string',
            description: 'Budget status',
            examples: ['draft', 'approved', 'active', 'frozen', 'closed'],
        },
    },
    relationships: {
        owner: {
            type: 'Worker',
            required: false,
            description: 'Budget owner',
        },
        department: {
            type: 'Department',
            required: false,
            description: 'Owning department',
        },
        team: {
            type: 'Team',
            required: false,
            description: 'Owning team',
        },
        expenses: {
            type: 'Expense[]',
            description: 'Budget expenses',
        },
        parent: {
            type: 'Budget',
            required: false,
            description: 'Parent budget',
        },
        children: {
            type: 'Budget[]',
            description: 'Sub-budgets',
        },
    },
    actions: [
        'create',
        'update',
        'submit',
        'approve',
        'allocate',
        'reallocate',
        'freeze',
        'unfreeze',
        'close',
        'archive',
    ],
    events: [
        'created',
        'updated',
        'submitted',
        'approved',
        'allocated',
        'reallocated',
        'frozen',
        'unfrozen',
        'thresholdWarning',
        'overBudget',
        'closed',
        'archived',
    ],
};
// =============================================================================
// Revenue
// =============================================================================
/**
 * Revenue entity
 *
 * Represents a revenue record.
 */
export const Revenue = {
    singular: 'revenue',
    plural: 'revenues',
    description: 'A revenue record',
    properties: {
        // Classification
        type: {
            type: 'string',
            optional: true,
            description: 'Revenue type',
            examples: ['subscription', 'one-time', 'usage', 'professional-services', 'licensing', 'other'],
        },
        category: {
            type: 'string',
            optional: true,
            description: 'Revenue category',
        },
        source: {
            type: 'string',
            optional: true,
            description: 'Revenue source',
        },
        // Amount
        amount: {
            type: 'number',
            description: 'Revenue amount',
        },
        currency: {
            type: 'string',
            optional: true,
            description: 'Currency code',
        },
        // Period
        period: {
            type: 'string',
            optional: true,
            description: 'Revenue period',
        },
        date: {
            type: 'date',
            optional: true,
            description: 'Revenue date',
        },
        // Recurring
        isRecurring: {
            type: 'boolean',
            optional: true,
            description: 'Is recurring revenue',
        },
        recurringPeriod: {
            type: 'string',
            optional: true,
            description: 'Recurring period',
            examples: ['monthly', 'quarterly', 'yearly'],
        },
        // Recognition
        recognized: {
            type: 'boolean',
            optional: true,
            description: 'Revenue recognized',
        },
        recognizedAt: {
            type: 'date',
            optional: true,
            description: 'Recognition date',
        },
        deferredAmount: {
            type: 'number',
            optional: true,
            description: 'Deferred revenue amount',
        },
        // Attribution
        segment: {
            type: 'string',
            optional: true,
            description: 'Business segment',
        },
        region: {
            type: 'string',
            optional: true,
            description: 'Geographic region',
        },
    },
    relationships: {
        product: {
            type: 'Product',
            required: false,
            description: 'Revenue product',
        },
        service: {
            type: 'Service',
            required: false,
            description: 'Revenue service',
        },
        customer: {
            type: 'Customer',
            required: false,
            description: 'Customer',
        },
        period: {
            type: 'FinancialPeriod',
            required: false,
            description: 'Financial period',
        },
    },
    actions: [
        'record',
        'update',
        'recognize',
        'defer',
        'void',
    ],
    events: [
        'recorded',
        'updated',
        'recognized',
        'deferred',
        'voided',
    ],
};
// =============================================================================
// Expense
// =============================================================================
/**
 * Expense entity
 *
 * Represents an expense record.
 */
export const Expense = {
    singular: 'expense',
    plural: 'expenses',
    description: 'An expense record',
    properties: {
        // Identity
        description: {
            type: 'string',
            description: 'Expense description',
        },
        // Classification
        type: {
            type: 'string',
            optional: true,
            description: 'Expense type',
            examples: ['payroll', 'cogs', 'marketing', 'sales', 'r&d', 'g&a', 'facilities', 'travel', 'software', 'services'],
        },
        category: {
            type: 'string',
            optional: true,
            description: 'Expense category',
        },
        subcategory: {
            type: 'string',
            optional: true,
            description: 'Expense subcategory',
        },
        // Amount
        amount: {
            type: 'number',
            description: 'Expense amount',
        },
        currency: {
            type: 'string',
            optional: true,
            description: 'Currency code',
        },
        // Date
        date: {
            type: 'date',
            description: 'Expense date',
        },
        period: {
            type: 'string',
            optional: true,
            description: 'Expense period',
        },
        // Recurring
        isRecurring: {
            type: 'boolean',
            optional: true,
            description: 'Is recurring expense',
        },
        recurringPeriod: {
            type: 'string',
            optional: true,
            description: 'Recurring period',
        },
        // Classification
        isCapex: {
            type: 'boolean',
            optional: true,
            description: 'Is capital expenditure',
        },
        isDeductible: {
            type: 'boolean',
            optional: true,
            description: 'Is tax deductible',
        },
        // Vendor
        vendor: {
            type: 'string',
            optional: true,
            description: 'Vendor name',
        },
        invoiceNumber: {
            type: 'string',
            optional: true,
            description: 'Invoice number',
        },
        // Status
        status: {
            type: 'string',
            description: 'Expense status',
            examples: ['draft', 'submitted', 'approved', 'rejected', 'paid', 'voided'],
        },
    },
    relationships: {
        submitter: {
            type: 'Worker',
            required: false,
            description: 'Who submitted',
        },
        approver: {
            type: 'Worker',
            required: false,
            description: 'Who approved',
        },
        budget: {
            type: 'Budget',
            required: false,
            description: 'Budget charged',
        },
        department: {
            type: 'Department',
            required: false,
            description: 'Department',
        },
        period: {
            type: 'FinancialPeriod',
            required: false,
            description: 'Financial period',
        },
    },
    actions: [
        'create',
        'update',
        'submit',
        'approve',
        'reject',
        'pay',
        'void',
    ],
    events: [
        'created',
        'updated',
        'submitted',
        'approved',
        'rejected',
        'paid',
        'voided',
    ],
};
// =============================================================================
// Investment
// =============================================================================
/**
 * Investment entity
 *
 * Represents a funding or investment round.
 */
export const Investment = {
    singular: 'investment',
    plural: 'investments',
    description: 'A funding or investment round',
    properties: {
        // Identity
        name: {
            type: 'string',
            description: 'Investment name/round',
        },
        description: {
            type: 'string',
            optional: true,
            description: 'Investment description',
        },
        // Type
        type: {
            type: 'string',
            optional: true,
            description: 'Investment type',
            examples: ['pre-seed', 'seed', 'series-a', 'series-b', 'series-c', 'series-d', 'growth', 'debt', 'grant'],
        },
        instrumentType: {
            type: 'string',
            optional: true,
            description: 'Instrument type',
            examples: ['equity', 'safe', 'convertible-note', 'debt', 'revenue-based'],
        },
        // Amount
        amount: {
            type: 'number',
            description: 'Investment amount',
        },
        currency: {
            type: 'string',
            optional: true,
            description: 'Currency code',
        },
        // Valuation
        preMoneyValuation: {
            type: 'number',
            optional: true,
            description: 'Pre-money valuation',
        },
        postMoneyValuation: {
            type: 'number',
            optional: true,
            description: 'Post-money valuation',
        },
        valuationCap: {
            type: 'number',
            optional: true,
            description: 'Valuation cap (for SAFEs/convertibles)',
        },
        discount: {
            type: 'number',
            optional: true,
            description: 'Discount percentage',
        },
        // Equity
        equityPercentage: {
            type: 'number',
            optional: true,
            description: 'Equity percentage sold',
        },
        sharesIssued: {
            type: 'number',
            optional: true,
            description: 'Shares issued',
        },
        pricePerShare: {
            type: 'number',
            optional: true,
            description: 'Price per share',
        },
        // Timeline
        announcedAt: {
            type: 'date',
            optional: true,
            description: 'Announcement date',
        },
        closedAt: {
            type: 'date',
            optional: true,
            description: 'Closing date',
        },
        // Terms
        interestRate: {
            type: 'number',
            optional: true,
            description: 'Interest rate (for debt)',
        },
        maturityDate: {
            type: 'date',
            optional: true,
            description: 'Maturity date (for debt)',
        },
        // Lead
        leadInvestor: {
            type: 'string',
            optional: true,
            description: 'Lead investor',
        },
        investors: {
            type: 'string',
            array: true,
            optional: true,
            description: 'All investors',
        },
        // Status
        status: {
            type: 'string',
            description: 'Investment status',
            examples: ['prospecting', 'negotiating', 'term-sheet', 'due-diligence', 'closing', 'closed', 'cancelled'],
        },
    },
    relationships: {
        business: {
            type: 'Business',
            description: 'Business receiving investment',
        },
    },
    actions: [
        'create',
        'update',
        'negotiate',
        'signTermSheet',
        'close',
        'announce',
        'cancel',
    ],
    events: [
        'created',
        'updated',
        'negotiated',
        'termSheetSigned',
        'closed',
        'announced',
        'cancelled',
    ],
};
// =============================================================================
// FinancialPeriod
// =============================================================================
/**
 * FinancialPeriod entity
 *
 * Represents a financial reporting period.
 */
export const FinancialPeriod = {
    singular: 'financial-period',
    plural: 'financial-periods',
    description: 'A financial reporting period',
    properties: {
        // Identity
        name: {
            type: 'string',
            description: 'Period name (e.g., "Q1 2025", "FY2025")',
        },
        // Type
        type: {
            type: 'string',
            description: 'Period type',
            examples: ['month', 'quarter', 'half-year', 'year'],
        },
        // Dates
        startDate: {
            type: 'date',
            description: 'Period start date',
        },
        endDate: {
            type: 'date',
            description: 'Period end date',
        },
        // Financials
        revenue: {
            type: 'number',
            optional: true,
            description: 'Total revenue',
        },
        cogs: {
            type: 'number',
            optional: true,
            description: 'Cost of goods sold',
        },
        grossProfit: {
            type: 'number',
            optional: true,
            description: 'Gross profit',
        },
        grossMargin: {
            type: 'number',
            optional: true,
            description: 'Gross margin percentage',
        },
        operatingExpenses: {
            type: 'number',
            optional: true,
            description: 'Operating expenses',
        },
        operatingIncome: {
            type: 'number',
            optional: true,
            description: 'Operating income (EBIT)',
        },
        operatingMargin: {
            type: 'number',
            optional: true,
            description: 'Operating margin percentage',
        },
        netIncome: {
            type: 'number',
            optional: true,
            description: 'Net income',
        },
        netMargin: {
            type: 'number',
            optional: true,
            description: 'Net margin percentage',
        },
        ebitda: {
            type: 'number',
            optional: true,
            description: 'EBITDA',
        },
        ebitdaMargin: {
            type: 'number',
            optional: true,
            description: 'EBITDA margin percentage',
        },
        // Cash
        cashStart: {
            type: 'number',
            optional: true,
            description: 'Cash at start',
        },
        cashEnd: {
            type: 'number',
            optional: true,
            description: 'Cash at end',
        },
        cashFlow: {
            type: 'number',
            optional: true,
            description: 'Net cash flow',
        },
        burnRate: {
            type: 'number',
            optional: true,
            description: 'Monthly burn rate',
        },
        runway: {
            type: 'number',
            optional: true,
            description: 'Runway in months',
        },
        // SaaS Metrics
        mrr: {
            type: 'number',
            optional: true,
            description: 'Monthly recurring revenue',
        },
        arr: {
            type: 'number',
            optional: true,
            description: 'Annual recurring revenue',
        },
        nrr: {
            type: 'number',
            optional: true,
            description: 'Net revenue retention',
        },
        grr: {
            type: 'number',
            optional: true,
            description: 'Gross revenue retention',
        },
        customers: {
            type: 'number',
            optional: true,
            description: 'Customer count',
        },
        arpu: {
            type: 'number',
            optional: true,
            description: 'Average revenue per user',
        },
        cac: {
            type: 'number',
            optional: true,
            description: 'Customer acquisition cost',
        },
        ltv: {
            type: 'number',
            optional: true,
            description: 'Lifetime value',
        },
        ltvCacRatio: {
            type: 'number',
            optional: true,
            description: 'LTV:CAC ratio',
        },
        churnRate: {
            type: 'number',
            optional: true,
            description: 'Churn rate',
        },
        // Currency
        currency: {
            type: 'string',
            optional: true,
            description: 'Reporting currency',
        },
        // Status
        status: {
            type: 'string',
            description: 'Period status',
            examples: ['open', 'closed', 'audited'],
        },
    },
    relationships: {
        business: {
            type: 'Business',
            description: 'Business',
        },
        revenues: {
            type: 'Revenue[]',
            description: 'Period revenues',
        },
        expenses: {
            type: 'Expense[]',
            description: 'Period expenses',
        },
        budgets: {
            type: 'Budget[]',
            description: 'Period budgets',
        },
        previous: {
            type: 'FinancialPeriod',
            required: false,
            description: 'Previous period',
        },
    },
    actions: [
        'create',
        'update',
        'close',
        'reopen',
        'audit',
    ],
    events: [
        'created',
        'updated',
        'closed',
        'reopened',
        'audited',
    ],
};
// =============================================================================
// Forecast
// =============================================================================
/**
 * Forecast entity
 *
 * Represents a financial forecast.
 */
export const Forecast = {
    singular: 'forecast',
    plural: 'forecasts',
    description: 'A financial forecast',
    properties: {
        // Identity
        name: {
            type: 'string',
            description: 'Forecast name',
        },
        description: {
            type: 'string',
            optional: true,
            description: 'Forecast description',
        },
        // Type
        type: {
            type: 'string',
            optional: true,
            description: 'Forecast type',
            examples: ['revenue', 'expense', 'cash', 'headcount', 'arr'],
        },
        scenario: {
            type: 'string',
            optional: true,
            description: 'Scenario',
            examples: ['base', 'optimistic', 'pessimistic', 'stretch'],
        },
        // Period
        startDate: {
            type: 'date',
            description: 'Forecast start date',
        },
        endDate: {
            type: 'date',
            description: 'Forecast end date',
        },
        granularity: {
            type: 'string',
            optional: true,
            description: 'Forecast granularity',
            examples: ['monthly', 'quarterly', 'yearly'],
        },
        // Values
        values: {
            type: 'json',
            optional: true,
            description: 'Forecast values by period',
        },
        total: {
            type: 'number',
            optional: true,
            description: 'Total forecasted amount',
        },
        currency: {
            type: 'string',
            optional: true,
            description: 'Currency code',
        },
        // Assumptions
        assumptions: {
            type: 'string',
            array: true,
            optional: true,
            description: 'Forecast assumptions',
        },
        growthRate: {
            type: 'number',
            optional: true,
            description: 'Assumed growth rate',
        },
        // Accuracy
        confidenceLevel: {
            type: 'number',
            optional: true,
            description: 'Confidence level (0-100)',
        },
        // Versioning
        version: {
            type: 'number',
            optional: true,
            description: 'Forecast version',
        },
        // Status
        status: {
            type: 'string',
            description: 'Forecast status',
            examples: ['draft', 'review', 'approved', 'superseded'],
        },
    },
    relationships: {
        owner: {
            type: 'Worker',
            required: false,
            description: 'Forecast owner',
        },
        basedOn: {
            type: 'FinancialPeriod[]',
            description: 'Historical periods used',
        },
    },
    actions: [
        'create',
        'update',
        'submit',
        'approve',
        'supersede',
        'archive',
    ],
    events: [
        'created',
        'updated',
        'submitted',
        'approved',
        'superseded',
        'archived',
    ],
};
// =============================================================================
// Exports
// =============================================================================
export const FinancialEntities = {
    Budget,
    Revenue,
    Expense,
    Investment,
    FinancialPeriod,
    Forecast,
};
export const FinancialCategories = {
    planning: ['Budget', 'Forecast'],
    transactions: ['Revenue', 'Expense'],
    funding: ['Investment'],
    reporting: ['FinancialPeriod'],
};
//# sourceMappingURL=financials.js.map