Gift Calculator

The only hackable open source gift calculation tool you´ll ever need. A CLI tool that suggests gift amounts based on a configurable base value with random variation, friend score, and nice score influences.

Quick Start

# Install via npm (recommended)
npm install -g gift-calc

# Calculate with defaults
gift-calc

# Setup your preferences
gift-calc init-config

# Custom amount for a friend
gift-calc -b 100 -f 8 --name "Alice"

Features

• 🎁 Smart gift amount calculation with configurable parameters
• 📊 Friend score system to bias amounts based on relationship closeness
• 😊 Nice score system with special cases for mean people
• ⚡ Quick convenience parameters for difficult people (--asshole, --dickhead)
• 📈 Fixed amount options (--max, --min) for predictable results
• ⚙️ Persistent configuration file support with update capability
• 📝 Automatic logging with log viewing functionality
• 🎯 Percentage-based variation for realistic randomness
• 📱 Simple command-line interface with dual command names
• 👮 Naughty list management (add/remove/list/search) with zero gift override
• 🎅 Automatic naughty list detection with "on naughty list!" notifications
• 🎁 Gift matching functionality to repeat previous gift amounts
• 💰 Automatic budget tracking with real-time spending analysis
• 📊 Spending pattern analysis with flexible time periods
• 🏆 Person ranking and toplist functionality for analyzing gift patterns
• 📅 Flexible date filtering for historical analysis and time-based gift insights

Installation

Via npm (recommended)

npm install -g gift-calc

Via Homebrew (macOS/Linux)

brew tap gift-calc/homebrew-gift-calc
brew install gift-calc

Via Install Script (Unix/Linux/macOS)

curl -fsSL https://raw.githubusercontent.com/gift-calc/gift-calc/master/bin/install.sh | sh

Via Docker

docker pull davidnossebro/gift-calc
docker run --rm davidnossebro/gift-calc -b 100 -r 30 -f 7

Usage

Basic Commands

gift-calc                    # Calculate with defaults/config
gcalc                        # Short alias
gift-calc init-config        # Setup configuration
gift-calc log                # View calculation history
gift-calc spendings          # Track spending patterns over time
gift-calc toplist            # Show top persons by gift amount
gcalc s                      # Short alias for spending tracking
gcalc tl                     # Short alias for toplist
gift-calc --help             # Show help

Common Examples

# Basic calculation
gift-calc

# For a good friend (with USD conversion display)
gift-calc -b 100 -f 8 --name "Alice" -c USD

# For someone you don't like
gift-calc --asshole --name "Kevin"

# Maximum amount for best friend
gift-calc -b 100 --max --name "Diana"

# Gift matching examples
gift-calc --match                      # Match last gift amount (any recipient)
gcalc -m Alice                        # Match last gift for Alice
gift-calc --match Bob --copy           # Match Bob's last gift and copy to clipboard

# Spending analysis
gift-calc spendings --days 30                        # Last 30 days spending
gcalc s --from 2024-01-01 --to 2024-12-31            # Date range spending  
gift-calc spendings --months 3                       # Last 3 months spending

# Naughty list management
gift-calc naughty-list Sven           # Add to naughty list
gift-calc naughty-list list           # List naughty people
gift-calc naughty-list --remove Sven  # Remove from naughty list

# Person ranking and toplist
gift-calc toplist                     # Top 10 by total gift amount
gcalc tl -n                          # Top 10 by nice score
gift-calc toplist --friend-score -l 5 # Top 5 by friend score
gift-calc toplist --from 2024-01-01 --to 2024-12-31  # Top 10 for 2024
gcalc tl --from 2024-12-01           # Top 10 from December 1 to today

Command Options

| Option | Description | Default | |--------|-------------|---------| | -b, --basevalue | Base gift amount | 70 | | -r, --variation | Variation percentage | 20 | | -f, --friend-score | Relationship closeness (1-10) | 5 | | -n, --nice-score | Person's niceness (0-10) | 5 | | -c, --currency | Display currency for conversion (default: same as base) | SEK | | --name | Gift recipient name | - | | --max | Set to maximum amount | - | | --min | Set to minimum amount | - | | --asshole | Set nice score to 0 (no gift) | - | | -m, --match [name] | Match previous gift amount (optionally for specific recipient) | - | | --no-log | Disable logging | false | | --copy | Copy amount to clipboard | false |

Spending Tracking Options

| Option | Description | Default | |--------|-------------|---------|
| spendings, s | Track and analyze spending patterns over time | - | | --from, -f | Start date for spending analysis (YYYY-MM-DD) | - | | --to, -t | End date for spending analysis (YYYY-MM-DD) | - | | --days | Show spending for last N days | - | | --weeks | Show spending for last N weeks | - | | --months | Show spending for last N months | - | | --years | Show spending for last N years | - |

Currency Configuration

Gift-calc uses a two-tier currency system:

• Base Currency: Used for all calculations and storage (default: SEK)
• Display Currency: Optional conversion for display (default: same as base)

When display currency differs from base, shows: "100 SEK (95 USD)" Exchange rates are cached for 24 hours and require internet for updates. Conversion failures show as: "100 SEK (conversion unavailable)"

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | GIFT_CALC_BASE_CURRENCY | Base currency for calculations | SEK |

Configuration

Setup persistent configuration:

gift-calc init-config    # Create initial config
gift-calc update-config  # Update existing config

Configuration file: ~/.config/gift-calc/.config.json

Configuration Format

{
  "baseValue": 70,
  "variation": 20,
  "friendScore": 5,
  "niceScore": 5,
  "baseCurrency": "SEK",
  "displayCurrency": "USD"
}

Migration Note: Existing configurations with currency field are automatically migrated to baseCurrency for backward compatibility.

Scoring Systems

Friend Score (1-10)

• 1-3: Acquaintance (bias toward lower amounts)
• 4-6: Regular friend (neutral)
• 7-8: Good friend (bias toward higher amounts)
• 9-10: Best friend/family (strong bias toward higher)

Nice Score (0-10)

• 0: Asshole (no gift!)
• 1-3: Mean person (10-30% of base value)
• 4-6: Average niceness (neutral)
• 7-10: Nice person (bias toward higher amounts)

Naughty List

Manage people who should receive no gifts:

gift-calc naughty-list <name>      # Add person
gcalc nl list                      # List all naughty people
gift-calc naughty-list --remove <name>  # Remove person
gcalc nl --search <term>           # Search naughty list

Budget Management

Manage gift budgets with automatic tracking and real-time spending analysis:

# Budget management
gift-calc budget add <amount> <from-date> <to-date> [description]  # Add new budget
gcalc b list                                                      # List all budgets  
gift-calc budget status                                          # Show current budget status
gift-calc budget edit <id> [options]                             # Edit existing budget

# Budget examples
gift-calc budget add 5000 2024-12-01 2024-12-31 "Christmas gifts"      # Add Christmas budget
gcalc b add 2000 2024-11-01 2024-11-30 "Birthday gifts"                # Add birthday budget
gift-calc budget edit 1 --amount 6000 --description "Updated Christmas" # Edit budget
gcalc b edit 1 --to-date 2025-01-15                                     # Extend budget

Automatic Budget Tracking

When an active budget exists, budget tracking is automatically displayed after each gift calculation:

# Normal calculation with budget tracking
gift-calc -b 100 --name "Alice"
# Output: 99.34 SEK for Alice
#         Budget: 1000 SEK | Used: 345.59 SEK | Remaining: 654.41 SEK | Ends: 2024-12-31 (25 days)

# Budget exceeded warning
gift-calc -b 200 --name "Bob"  
# Output: 201.25 SEK for Bob
#         ⚠️  BUDGET EXCEEDED! Budget: 1000 SEK | Used: 1096.73 SEK | Over by: 96.73 SEK | Ends: 2024-12-31 (25 days)

Features:

• Real-time tracking: Automatic display after each calculation
• Currency filtering: Only amounts matching budget currency are included
• Multi-currency support: Different currencies tracked separately with warnings
• Status indicators: Clear visual feedback for budget status
• Flexible periods: Support for overlapping and non-overlapping budget periods

Person Ranking & Toplist

View ranked lists of persons by different criteria to analyze your gift-giving patterns:

# Basic toplist commands
gift-calc toplist                      # Top 10 persons by total gift amount
gcalc tl                              # Short form
gift-calc toplist --nice-score         # Top 10 persons by nice score
gift-calc toplist --friend-score       # Top 10 persons by friend score
gift-calc toplist --gift-count         # Top 10 persons by gift count
gift-calc toplist --length 20          # Top 20 persons by total gifts

# Combined options
gcalc tl -n -l 5                      # Top 5 by nice score
gift-calc toplist -f --length 15       # Top 15 by friend score
gcalc tl -g -l 3                      # Top 3 by gift count

# Time filtering
gift-calc toplist --from 2024-01-01 --to 2024-12-31  # Top 10 for 2024
gcalc tl --from 2024-12-01 -n           # Top 10 by nice score from December 1
gift-calc toplist --from 2024-06-01 --to 2024-08-31 -l 5  # Top 5 for summer gifts

Toplist Options

| Option | Description | Default | |--------|-------------|---------| | toplist, tl | Show person ranking | - | | -n, --nice-score | Sort by nice score (highest first) | total | | -f, --friend-score | Sort by friend score (highest first) | total | | -g, --gift-count | Sort by gift count (highest first) | total | | -l, --length | Number of results to show | 10 | | -c, --currency | Filter by specific currency | - | | --from | Start date filter (YYYY-MM-DD) | - | | --to | End date filter (YYYY-MM-DD) | - | | --list-currencies | Show available currencies | - |

Sample Output

$ gift-calc toplist
Top 4 Persons (Total Gifts):

1. Alice: 1,250.50 SEK, 100.00 USD (nice: 9, friend: 8)
2. Bob: 875.25 USD (nice: 7, friend: 6)
3. Charlie: 425.00 SEK (nice: 5, friend: 9)
4. David: 150.00 SEK

$ gift-calc toplist --gift-count
Top 4 Persons (Gift Count):

1. Alice: 2 gifts (nice: 9, friend: 8)
2. Bob: 1 gift (nice: 7, friend: 6)
3. Charlie: 1 gift (nice: 5, friend: 9)
4. David: 1 gift

Note: For toplist command help, use the global help flag: gift-calc --help

Features:

• Multi-currency support: Shows gift totals in original currencies
• Score integration: Displays nice and friend scores when available
• Flexible sorting: Sort by total gifts, nice score, or friend score
• Configurable length: Show any number of top results
• Time filtering: Analyze gift patterns by date range for historical insights
• Currency filtering: Focus analysis on specific currencies
• Combined data: Merges person configuration and gift history data

MCP (Model Context Protocol) Support

Gift-calc includes built-in MCP server support, enabling direct integration with AI assistants like Claude, GPT, and other LLMs. Use gift-calc tools directly in AI conversations for natural gift calculations, budget management, and naughty list operations.

📖 Complete documentation: MCP.md - installation, setup, troubleshooting, and examples

Development

# Clone and setup
git clone https://github.com/gift-calc/gift-calc.git
cd gift-calc
npm install

# Test locally
node index.js --help
npm link                    # Link for global testing
npm test                    # Run tests

More Information

• Full Documentation: Website
• Contributing: docs/CONTRIBUTING.md
• Changelog: docs/CHANGELOG.md
• Security: docs/SECURITY.md
• Code of Conduct: docs/CODE_OF_CONDUCT.md
• Issues: GitHub Issues
• Discussions: GitHub Discussions

License

ISC License - see LICENSE file for details.

Need help? Run gift-calc --help for quick reference.