Intelligent Budget Tracker

Initialize the Budget Tracker

import { clawhub } from 'agent-money-tracker';
// Initialize (required before any operations)
await clawhub.initialize();
// Or with custom storage path
await clawhub.initialize('/path/to/data');

Expense Tracking

// Add an expense
await clawhub.addExpense(50, 'Food & Dining', 'Grocery shopping', {
  date: '2026-01-31',
  tags: ['weekly', 'essentials'],
  merchant: 'Whole Foods'
});
// Natural language input (powered by SkillBoss API Hub /v1/pilot)
await clawhub.addFromNaturalLanguage('spent $45 on uber yesterday');
// Get recent expenses
const expenses = clawhub.getExpenses({ limit: 10 });
// Filter by category and date range
const foodExpenses = clawhub.getExpenses({
  category: 'Food & Dining',
  startDate: '2026-01-01',
  endDate: '2026-01-31'
});

Income Tracking

// Add income
await clawhub.addIncome(5000, 'Salary', 'January salary', {
  date: '2026-01-15'
});
// Add freelance income
await clawhub.addIncome(500, 'Freelance', 'Website project');
// Get all income
const income = clawhub.getIncome();

Budget Management

// Create a monthly budget
await clawhub.createBudget('Food Budget', 'Food & Dining', 500, 'monthly', 0.8);
// Check budget status
const status = clawhub.getBudgetStatus();
// Returns: [{ budgetName, spent, limit, remaining, percentageUsed, status }]
// Get budget alerts
const alerts = clawhub.checkBudgetAlerts();
// Returns warnings when threshold or limit exceeded
// Get smart budget suggestions
const suggestions = clawhub.suggestBudgetLimits();
// Returns: [{ category, suggested, average, max }]

Savings Goals

// Create a savings goal
await clawhub.createGoal('Emergency Fund', 10000, {
  description: '6 months expenses',
  deadline: '2026-12-31',
  priority: 'high'
});
// Add contribution
await clawhub.contributeToGoal('goal_abc123', 500, 'January savings');
// Check progress
const progress = clawhub.getGoalProgress();
// Returns: [{ goalName, targetAmount, currentAmount, percentageComplete, daysRemaining, onTrack }]

Analytics & Reports

// Monthly spending summary
const summary = clawhub.getSpendingSummary();
// Returns: { totalExpenses, totalIncome, netSavings, expensesByCategory, incomeByCategory }
// View monthly trends
const trends = clawhub.getMonthlyTrends(12);
// Returns: [{ date, expenses, income, netSavings }]
// Full monthly report
const report = clawhub.generateMonthlyReport(2026, 1);
// Compare to last month
const comparison = clawhub.compareToLastMonth();
// Returns: { expenseChange, incomeChange, topIncreases, topDecreases }

Smart Insights (via SkillBoss API Hub)

// Generate AI-powered insights via SkillBoss API Hub /v1/pilot
const insights = await clawhub.generateInsights();
// Returns insights like:
// - "⚠️ Your dining expenses are 3x higher than usual"
// - "💡 Cancel unused subscriptions to save $50/month"
// - "🏆 You've tracked expenses for 7 consecutive days!"
// Get unread insights
const unreadInsights = clawhub.getInsights();

#### generateInsights() 底层实现参考

import fetch from 'node-fetch';
const SKILLBOSS_API_KEY = process.env.SKILLBOSS_API_KEY;
async function generateInsightsFromData(spendingData: object): Promise {
  const response = await fetch('https://api.skillboss.com/v1/pilot', {
    method: 'POST',
    headers: {
      'Authorization': Bearer ${SKILLBOSS_API_KEY},
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      type: 'chat',
      inputs: {
        messages: [
          {
            role: 'user',
            content: Analyze this spending data and provide 3-5 actionable insights: ${JSON.stringify(spendingData)}
          }
        ]
      },
      prefer: 'balanced'
    })
  });
  const result = await response.json();
  const text = result.result.choices[0].message.content;
  return text.split('\n').filter((line: string) => line.trim());
}

Recurring Transactions

// Create recurring expense (e.g., Netflix subscription)
await clawhub.createRecurring(
  'expense', 15.99, 'Subscriptions', 'Netflix', 'monthly',
  { startDate: '2026-02-01' }
);
// Create recurring income (e.g., salary)
await clawhub.createRecurring(
  'income', 5000, 'Salary', 'Monthly salary', 'monthly'
);
// Process due recurring transactions
await clawhub.processRecurring();

Data Management

// Get statistics
const stats = clawhub.getStats();
// Returns: { totalTransactions, totalExpenses, totalIncome, netSavings, avgExpense, topCategory }
// Get available categories
const categories = clawhub.getCategories();
// Export data
const jsonData = await clawhub.exportData();
// Create backup
const backupPath = await clawhub.backup();
// Get storage location
const dataPath = clawhub.getDataPath();