nutrition-tracker

# nutrition-tracker Skill

Interact with the nutrition-tracker API to manage food databases, log diary entries, and query nutrition summaries.

## When to use

Use this skill when the user wants to:
- Add or search custom foods in the local food database
- Log food entries to a daily diary
- Retrieve calorie or macro totals for a date
- View diary history or weekly trends
- Manage meal types or daily nutrition goals
- Export diary data as CSV or PDF

## Prerequisites

- Server running: `pnpm dev` or `node dist/server/index.js`
- Default port: `3852`
- No authentication required (local-only service)

## Privacy model

This server stores all data in a local SQLite database. No data is sent to external services. Food names and nutrition values are never written to server logs.

---

## Quick reference: curl examples

### Foods

Search foods by name:
```bash
curl "http://localhost:3852/api/foods?q=oats&limit=10"
```

Create a custom food:
```bash
curl -s -X POST http://localhost:3852/api/foods \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sample Oats - Generic",
    "serving_size": 100,
    "serving_unit": "g",
    "calories": 350,
    "protein_g": 12,
    "carbs_g": 60,
    "fat_g": 6,
    "fiber_g": 10,
    "sugar_g": 1,
    "sodium_mg": 5
  }'
```

Get a food by ID:
```bash
curl "http://localhost:3852/api/foods/1"
```

Update a food:
```bash
curl -s -X PUT http://localhost:3852/api/foods/1 \
  -H "Content-Type: application/json" \
  -d '{"calories": 355, "protein_g": 13}'
```

Delete a food:
```bash
curl -s -X DELETE http://localhost:3852/api/foods/1
```

### Diary

Get diary entries for a date:
```bash
curl "http://localhost:3852/api/diary?date=2026-03-20"
```

Add a diary entry (quantity is a multiplier of the food's serving_size):
```bash
curl -s -X POST http://localhost:3852/api/diary \
  -H "Content-Type: application/json" \
  -d '{
    "log_date": "2026-03-20",
    "meal_id": 1,
    "food_id": 1,
    "quantity": 0.8,
    "notes": ""
  }'
```

Update quantity for an entry:
```bash
curl -s -X PUT http://localhost:3852/api/diary/5 \
  -H "Content-Type: application/json" \
  -d '{"quantity": 1.0}'
```

Delete a diary entry:
```bash
curl -s -X DELETE http://localhost:3852/api/diary/5
```

### Diary summary (macro totals)

Get totals for a date - macros are computed by joining diary_entries with foods:
```bash
curl "http://localhost:3852/api/diary/summary?date=2026-03-20"
```

Response:
```json
{
  "date": "2026-03-20",
  "calories": 1420,
  "protein_g": 96,
  "carbs_g": 185,
  "fat_g": 42,
  "fiber_g": 14,
  "entry_count": 7
}
```

### Diary history (multi-day)

```bash
curl "http://localhost:3852/api/diary/history?from=2026-03-01&to=2026-03-20"
```

Returns one row per logged day, sorted chronologically.

### Meals

List meal types:
```bash
curl "http://localhost:3852/api/meals"
```

Create a meal type:
```bash
curl -s -X POST http://localhost:3852/api/meals \
  -H "Content-Type: application/json" \
  -d '{"name": "Pre-Workout", "sort_order": 5}'
```

Update meal name:
```bash
curl -s -X PUT http://localhost:3852/api/meals/5 \
  -H "Content-Type: application/json" \
  -d '{"name": "Evening Snack"}'
```

Delete a meal type (only if no diary entries reference it):
```bash
curl -s -X DELETE http://localhost:3852/api/meals/5
```

### Goals

List all goals:
```bash
curl "http://localhost:3852/api/goals"
```

Update a goal target:
```bash
curl -s -X PATCH http://localhost:3852/api/goals/calories \
  -H "Content-Type: application/json" \
  -d '{"target_value": 2200}'
```

Valid `goal_type` values: `calories`, `protein_g`, `carbs_g`, `fat_g`, `fiber_g`.

### Stats

Weekly calorie and macro trends (last 7 days):
```bash
curl "http://localhost:3852/api/stats/weekly"
```

Most frequently logged foods:
```bash
curl "http://localhost:3852/api/stats/foods?limit=10"
```

### Export

Download all diary entries as CSV:
```bash
curl -o diary.csv "http://localhost:3852/api/export/csv?from=2026-03-01&to=2026-03-20"
```

CSV columns: `log_date, meal, food_name, quantity, serving_unit, calories, protein_g, carbs_g, fat_g, fiber_g`

Download PDF report:
```bash
curl -o report.pdf "http://localhost:3852/api/export/pdf?from=2026-03-01&to=2026-03-20"
```

### Settings

Get settings:
```bash
curl "http://localhost:3852/api/settings"
```

Update settings:
```bash
curl -s -X PATCH http://localhost:3852/api/settings \
  -H "Content-Type: application/json" \
  -d '{"key": "calorie_unit", "value": "kcal"}'
```

---

## API reference

| Method | Path | Description |
|---|---|---|
| GET | `/api/foods` | List/search foods (`q`, `limit`) |
| POST | `/api/foods` | Create custom food |
| GET | `/api/foods/:id` | Get food by ID |
| PUT | `/api/foods/:id` | Update food |
| DELETE | `/api/foods/:id` | Delete food |
| GET | `/api/meals` | List meal types |
| POST | `/api/meals` | Create meal type |
| PUT | `/api/meals/:id` | Update meal name/order |
| DELETE | `/api/meals/:id` | Delete meal type |
| GET | `/api/diary` | Diary entries for date (`date`) |
| POST | `/api/diary` | Add diary entry |
| PUT | `/api/diary/:id` | Update entry quantity |
| DELETE | `/api/diary/:id` | Remove diary entry |
| GET | `/api/diary/summary` | Macro totals for date (`date`) |
| GET | `/api/diary/history` | Per-day totals (`from`, `to`) |
| GET | `/api/goals` | List nutrition goals |
| PATCH | `/api/goals/:goalType` | Update goal target |
| GET | `/api/stats/weekly` | Last-7-days calorie trend |
| GET | `/api/stats/foods` | Top foods by frequency |
| GET | `/api/export/csv` | CSV stream (`from`, `to`) |
| GET | `/api/export/pdf` | PDF report (`from`, `to`) |
| GET | `/api/settings` | Get all settings |
| PATCH | `/api/settings` | Update a setting |

---

## Default meal types

| ID | Name | sort_order |
|---|---|---|
| 1 | Breakfast | 0 |
| 2 | Lunch | 1 |
| 3 | Dinner | 2 |
| 4 | Snack | 3 |

---

## Default goals

| goal_type | target_value |
|---|---|
| calories | 2000 |
| protein_g | 150 |
| carbs_g | 250 |
| fat_g | 65 |

---

## Macro calculation

Macros are never stored in `diary_entries`. They are computed at query time:

```
entry_calories = food.calories * entry.quantity
entry_protein  = food.protein_g * entry.quantity
entry_carbs    = food.carbs_g * entry.quantity
entry_fat      = food.fat_g * entry.quantity
```

`quantity` is a multiplier of the food's `serving_size`. A quantity of `1.0` means one full serving. A quantity of `0.5` means half a serving.

---

## Environment variables

| Variable | Default | Description |
|---|---|---|
| `PORT` | `3852` | Server port |
| `DATA_DIR` | `./data` | SQLite file location |
| `EXPORT_DIR` | `./exports` | CSV/PDF output directory |
| `LOG_LEVEL` | `info` | Pino log level |
| `NODE_ENV` | `development` | development / production |

---

## Validation rules

- `calories`, `protein_g`, `carbs_g`, `fat_g`, `fiber_g`, `sugar_g`, `sodium_mg`: must be >= 0
- `serving_size`: must be > 0
- `quantity` in diary entries: must be > 0
- `name` for foods and meals: required, non-empty string
- `log_date`: must be a valid YYYY-MM-DD string
- `target_value` for goals: must be >= 0

All inputs validated with Zod before any database access.

---

## Troubleshooting

**POST /api/foods returns HTTP 400**
Zod validation failed. Check that all numeric nutrition fields are >= 0 and `serving_size` > 0.

**DELETE /api/meals/:id returns HTTP 409**
The meal type has diary entries referencing it. Remove those entries first or use a different meal type.

**GET /api/diary/summary returns zeros**
No diary entries exist for that date. Verify with `GET /api/diary?date=YYYY-MM-DD`.

**CSV export is empty**
No diary entries in the requested date range. Confirm entries exist via the history endpoint.

**Server not starting**
Check `DATA_DIR` is writable. SQLite requires write access to create the `.db` file.