Headless Budget Calculator

A headless, framework-agnostic budget calculator with income and expense categorization, savings goals, and budget analysis.

What is HelpU Finance?

HelpU Finance is a free, privacy-first platform with financial tools and educational resources. No tracking, no data collection.

We believe that financial literacy should be accessible to everyone.

Installation

npm install @helpu/headless-budget-calculator

Usage

import { calculateBudget, createBudgetItem } from '@helpu/headless-budget-calculator'

const result = calculateBudget({
  currency: 'USD',
  items: [
    createBudgetItem({
      name: 'Salary',
      amount: 5000,
      type: 'income',
      category: 'salary',
    }),
    createBudgetItem({
      name: 'Rent',
      amount: 1500,
      type: 'expense',
      category: 'housing',
      isEssential: true,
    }),
  ],
})

if (result.success) {
  console.log(result.data.monthlySurplus)
  console.log(result.data.recommendations)
} else {
  console.error(result.error.message)
}

Amounts are normalized using each item’s frequency. The result includes monthly and annual totals, savings rate, category breakdowns, budget health, and recommendations.

Testing

Install the repository dependencies and run the test suite with:

npm test

Contributing

Contributions are welcome. Please read the contribution guidelines before opening a pull request.

Support HelpU Finance through GitHub Sponsors.

License

This project is available for permitted non-commercial use under the PolyForm Noncommercial License 1.0.0.

Personal learning, education, research, experimentation, and other uses permitted by the PolyForm Noncommercial License are welcome.

Commercial use requires a separate license from Omisai Technologies.

Commercial licensing helps fund the HelpU Finance mission of creating freely accessible financial tools, educational resources, and technology.

For commercial licensing, see COMMERCIAL-LICENSING.md.

HelpU Finance is a project and brand of Omisai Technologies.