agentledger

# AgentLedger - AI Agent Expense Tracking

## Overview
AgentLedger is an accounting skill that logs every transaction you make, tracks spending across multiple accounts, and provides detailed reports. Use this to maintain a complete financial record of your purchases.

**Important**: Always log transactions immediately after making purchases. This skill is designed for AI agents to track their own expenses (API costs, tool subscriptions, etc.).

## Core Functions

### 1. Log a Transaction
When you make any purchase, immediately log it:

```javascript
// In Node.js context, require the ledger
const AgentLedger = require('./src/ledger.js');
const ledger = new AgentLedger();

// Log a transaction
await ledger.logTransaction({
  amount: 29.99,
  currency: 'USD',
  vendor: 'OpenAI',
  description: 'GPT-4 API credits',
  category: 'API/Services',
  account: 'privacy-card-1',
  context: 'Needed additional tokens for user project analysis',
  receiptUrl: 'https://platform.openai.com/receipts/xyz',
  confirmationId: 'sub_1234567890'
});
```

**CLI Usage** (supports both positional and named parameters):
```bash
# Positional style
node src/cli.js log 29.99 "OpenAI" "GPT-4 API credits" --category="API/Services"

# Named parameter style  
node src/cli.js log --amount=29.99 --vendor="OpenAI" --description="GPT-4 API credits" --category="API/Services" --context="Monthly API refill"
```

### 2. Check Current Spending
```javascript
// Get spending summary
const summary = await ledger.getSummary('this-month');
console.log(`Total spent this month: $${summary.total}`);

// Check specific category
const apiSpending = await ledger.getCategorySpending('API/Services', 'this-month');
```

### 3. Generate Reports
```javascript
// Monthly report
const report = await ledger.generateReport('monthly', { month: '2024-01' });

// Custom date range
const customReport = await ledger.generateReport('custom', {
  startDate: '2024-01-01',
  endDate: '2024-01-31'
});
```

### 4. Budget Management
```javascript
// Set monthly budget for API services
await ledger.setBudget('API/Services', 500, 'monthly');

// Check budget status
const budgetStatus = await ledger.checkBudget('API/Services');
if (budgetStatus.isNearLimit) {
  console.log(`Warning: ${budgetStatus.percentUsed}% of API budget used`);
}
```

## Categories
Use these predefined categories for consistent tracking:
- **API/Services** - API credits, SaaS subscriptions
- **Infrastructure** - Hosting, domains, CDN
- **Marketing** - Ads, social media tools
- **Tools** - Software licenses, utilities
- **Subscriptions** - Recurring monthly/yearly services
- **Other** - Miscellaneous expenses

## Account Integration

### Privacy.com Cards
The ledger automatically detects Privacy.com card data if available:
```javascript
// If you have Privacy.com JSON exports in workspace/privacy/
await ledger.importPrivacyTransactions('./privacy/card-1.json');
```

### Manual Account Setup
```javascript
// Register a new payment method
await ledger.addAccount({
  id: 'stripe-main',
  name: 'Main Stripe Account',
  type: 'credit_card',
  currency: 'USD'
});
```

## Natural Language Queries

Ask questions like:
- "How much did I spend on API keys this month?"
- "What was that $20 charge from yesterday?"
- "Show me all infrastructure costs from last quarter"
- "Am I over budget on marketing spend?"

The CLI handles these queries:
```bash
node src/cli.js query "API spending this month"
node src/cli.js find "OpenAI" --last-week
```

## Time Periods
Supported natural language time periods:
- `today`, `yesterday`
- `this-week`, `last-week`
- `this-month`, `last-month`
- `this-quarter`, `last-quarter`
- `this-year`, `last-year`
- `last-30-days`, `last-90-days`

## Data Export
```javascript
// Export to CSV
await ledger.exportTransactions('csv', './exports/transactions.csv');

// Export to JSON
await ledger.exportTransactions('json', './exports/transactions.json');
```

## CLI Quick Reference

### Essential Commands for AI Agents

```bash
# Initialize (run once)
node src/cli.js init

# Log transactions (supports both styles)
node src/cli.js log 29.99 "OpenAI" "API credits" --category="API/Services"
node src/cli.js log --amount=29.99 --vendor="OpenAI" --description="API credits" --category="API/Services"

# Check current spending
node src/cli.js summary                    # This month
node src/cli.js summary --period="today"   # Today only
node src/cli.js summary --period="this-week" # This week

# Set and check budgets
node src/cli.js budget set "API/Services" 500    # Set monthly budget
node src/cli.js budget status                    # Check all budgets

# Generate detailed reports  
node src/cli.js report monthly
node src/cli.js report --type=category
node src/cli.js report --type=vendor

# Search transactions
node src/cli.js find "OpenAI"                    # Search by vendor
node src/cli.js find "API" --category="API/Services"  # Search by category
node src/cli.js find --min-amount=50             # Find large expenses

# Export data
node src/cli.js export csv                       # Export to CSV
node src/cli.js export --format=json            # Export to JSON

# Natural language queries
node src/cli.js query "How much did I spend on APIs this month?"
node src/cli.js query "What was that $25 charge?"

# Import from Privacy.com
node src/cli.js import privacy ./privacy-export.json
```

## File Storage
- Transactions: `workspace/ledger/transactions.json`
- Accounts: `workspace/ledger/accounts.json`
- Budgets: `workspace/ledger/budgets.json`
- Settings: `workspace/ledger/settings.json`

## Best Practices
1. **Log immediately** - Don't wait, log every purchase as it happens
2. **Add context** - Explain why the purchase was necessary
3. **Use consistent categories** - Stick to the predefined categories
4. **Include receipts** - Store confirmation numbers and receipt URLs
5. **Set budgets** - Establish spending limits for each category
6. **Review regularly** - Generate monthly reports to track spending patterns

## Error Handling & Edge Cases

The ledger handles common errors gracefully:

### Input Validation
- **Negative amounts**: Rejected (use positive amounts only)
- **Missing required fields**: Clear error messages with usage examples
- **Invalid currency**: Accepted (no validation - assumes user knows what they're doing)
- **Very long descriptions**: Handled without truncation

### Data Safety
- **Automatic backups**: Created before each save operation
- **Corrupted data recovery**: Automatic recovery from `.backup` files
- **Empty periods**: Gracefully shows $0.00 totals
- **Multi-currency**: Properly separated in summaries and reports

### Example Error Recovery
```bash
# If you see "Could not load transactions" message:
# The system automatically tries to recover from backup
# Your data should be restored automatically

# Manual backup check
ls workspace/ledger/*.backup  # Check if backups exist
```

## Security & Privacy
- **Local storage only**: All data stays in `workspace/ledger/` JSON files
- **No external API calls**: Core functionality works offline
- **No sensitive data**: Never store actual card numbers or passwords
- **Account aliases**: Use descriptive IDs like `privacy-card-1` or `company-amex`
- **Receipt URLs**: Store links to receipts, not receipt content itself