sleep-tracker

# sleep-tracker Skill

Interact with the sleep-tracker API to log sleep entries, query trends, manage goals, and export data.

## When to use

Use this skill when the user wants to:
- Log a nightly sleep entry with bedtime, wake time, quality score, and optional stage data
- Retrieve sleep history or stats
- Manage tags, goals, or settings
- Export data as CSV or PDF

## Prerequisites

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

## Privacy model

Sleep values (duration, quality score, stage percentages) are never written to server logs. All data stays in a local SQLite database.

---

## Quick reference: curl examples

### Entries

List recent entries:
```bash
curl "http://localhost:3853/api/entries?limit=7"
```

List by date range:
```bash
curl "http://localhost:3853/api/entries?from=2026-03-01&to=2026-03-20"
```

Get most recent entry:
```bash
curl "http://localhost:3853/api/entries/latest"
```

Get entry by ID:
```bash
curl "http://localhost:3853/api/entries/1"
```

Create a sleep entry:
```bash
curl -s -X POST http://localhost:3853/api/entries \
  -H "Content-Type: application/json" \
  -d '{
    "sleep_date": "2026-03-19",
    "bedtime": "2026-03-19T22:30:00",
    "wake_time": "2026-03-20T06:15:00",
    "quality_score": 8,
    "deep_pct": 20,
    "light_pct": 50,
    "rem_pct": 25,
    "awake_pct": 5,
    "notes": "",
    "tag_ids": [1, 2]
  }'
```

Notes:
- `duration_min` is computed from bedtime and wake_time and stored automatically.
- `deep_pct + light_pct + rem_pct + awake_pct` must equal 100 when all four are provided. Returns HTTP 400 otherwise.
- `quality_score` must be 1-10. Returns HTTP 400 otherwise.
- Stage fields are optional. Omit all four if no stage data is available.

Update an entry:
```bash
curl -s -X PUT http://localhost:3853/api/entries/1 \
  -H "Content-Type: application/json" \
  -d '{"quality_score": 9, "notes": "Felt great"}'
```

Delete an entry:
```bash
curl -s -X DELETE http://localhost:3853/api/entries/1
```

### Tags

List tags:
```bash
curl "http://localhost:3853/api/tags"
```

Create a tag:
```bash
curl -s -X POST http://localhost:3853/api/tags \
  -H "Content-Type: application/json" \
  -d '{"name": "Exercise", "color": "#7c3aed"}'
```

Update a tag:
```bash
curl -s -X PUT http://localhost:3853/api/tags/1 \
  -H "Content-Type: application/json" \
  -d '{"name": "Workout", "color": "#0891b2"}'
```

Delete a tag:
```bash
curl -s -X DELETE http://localhost:3853/api/tags/1
```

### Goals

List goals:
```bash
curl "http://localhost:3853/api/goals"
```

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

Valid `goal_type` values: `duration_min`, `quality_score`, `bedtime_by`.

For `bedtime_by`, `target_value` is minutes since midnight. `23:00 = 1380`, `22:30 = 1350`.

### Stats

Weekly trend (last 7 days):
```bash
curl "http://localhost:3853/api/stats/weekly"
```

Monthly summary (last 30 days):
```bash
curl "http://localhost:3853/api/stats/monthly"
```

Cumulative 7-day sleep debt:
```bash
curl "http://localhost:3853/api/stats/debt"
```

Response includes `debt_min` (positive = deficit) and per-day breakdown.

Bedtime consistency score:
```bash
curl "http://localhost:3853/api/stats/consistency"
```

Response includes `stddev_min` (standard deviation of bedtime in minutes) and a `rating` label.

### Export

CSV:
```bash
curl -o sleep.csv "http://localhost:3853/api/export/csv?from=2026-03-01&to=2026-03-20"
```

CSV columns: `sleep_date, bedtime, wake_time, duration_min, quality_score, deep_pct, light_pct, rem_pct, awake_pct, tags, notes`

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

### Settings

```bash
curl "http://localhost:3853/api/settings"
curl -s -X PATCH http://localhost:3853/api/settings \
  -H "Content-Type: application/json" \
  -d '{"key": "time_format", "value": "24h"}'
```

---

## API reference

| Method | Path | Description |
|---|---|---|
| GET | `/api/entries` | List entries (`from`, `to`, `limit`) |
| POST | `/api/entries` | Create sleep entry |
| GET | `/api/entries/latest` | Most recent entry |
| GET | `/api/entries/:id` | Get entry by ID |
| PUT | `/api/entries/:id` | Update entry |
| DELETE | `/api/entries/:id` | Delete entry |
| GET | `/api/tags` | List tags |
| POST | `/api/tags` | Create tag |
| PUT | `/api/tags/:id` | Update tag |
| DELETE | `/api/tags/:id` | Delete tag |
| GET | `/api/goals` | List goals |
| PATCH | `/api/goals/:goalType` | Update goal |
| GET | `/api/stats/weekly` | Last-7-days trend |
| GET | `/api/stats/monthly` | Last-30-days summary |
| GET | `/api/stats/debt` | 7-day sleep debt |
| GET | `/api/stats/consistency` | Bedtime consistency |
| GET | `/api/export/csv` | CSV export |
| GET | `/api/export/pdf` | PDF report |
| GET | `/api/settings` | Settings |
| PATCH | `/api/settings` | Update setting |

---

## Default goals

| goal_type | target_value | meaning |
|---|---|---|
| duration_min | 480 | 8 hours |
| quality_score | 7 | quality 7/10 |
| bedtime_by | 1380 | in bed by 23:00 |

---

## Validation rules

- `quality_score`: integer 1-10
- `deep_pct + light_pct + rem_pct + awake_pct`: must sum to 100 +/- 1 when all four provided
- `sleep_date`: YYYY-MM-DD, unique per day
- `bedtime`, `wake_time`: valid ISO 8601 datetime strings
- `wake_time` must be after `bedtime`
- `color` for tags: valid CSS hex color (e.g. `#0891b2`)

---

## Environment variables

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

---

## Troubleshooting

**POST returns HTTP 400 "stage percentages must sum to 100"**
Verify that `deep_pct + light_pct + rem_pct + awake_pct = 100`. If you do not have stage data, omit all four fields entirely.

**POST returns HTTP 409 "sleep_date already exists"**
Each `sleep_date` is unique. Use PUT to update an existing entry.

**GET /api/stats/debt returns debt_min: 0**
No entries in the last 7 days. Log some entries first.

**GET /api/stats/consistency returns null**
Fewer than 2 entries available for the calculation period (requires 14 days).

**Duration seems wrong**
`duration_min` is `(wake_time - bedtime)` in minutes. Ensure `wake_time` is after `bedtime`. For entries where wake is next day, the ISO datetime strings handle this correctly.