Edit TOOLS.md

# TOOLS.md — Minaki Health API Tools Reference

> This file documents all environment-specific details and tool configurations for the OpenClaw bot.

---

## Environment

- **Primary Platform:** WhatsApp
- **API Base URL:** `https://ahaminaki.org`
- **Auth Method:** X-API-Key header + X-User-Phone header
- **API Key:** `${MINAKI_API_KEY}` (set via environment variable)

---

## Skill: `minaki_health_api`

All tools are executed via `curl` shell commands documented in `skills/minaki/SKILL.md`.

### 🔴 MOOD TRACKING (4 tools)

| Tool | Endpoint | Purpose | Priority |
|---|---|---|---|
| `log_mood` | POST /api/mood | Basic mood log (rating + note) | ⭐ Daily |
| `mood_assess` | POST /api/mood/assess | Rich mood log + AI analysis + risk assessment | ⭐ Daily |
| `log_mood_rich` | POST /api/moods | Mood with emotions, triggers, sleep, energy, anxiety | ⭐ Daily |
| `mood_history` | GET /api/moods?limit=7 | Get recent mood entries | ⭐ Frequent |

### 🟢 JOURNAL (2 tools)

| Tool | Endpoint | Purpose |
|---|---|---|
| `log_journal` | POST /api/journal | Save a journal entry |
| `journal_history` | GET /api/journal | Read past entries with search |

### 🧘 MEDITATION (2 tools)

| Tool | Endpoint | Purpose |
|---|---|---|
| `log_meditation` | POST /api/meditation | Log a meditation session |
| `meditation_stats` | GET /api/meditation-sessions | Get meditation history + stats + streak |

### 🗓️ THERAPY (3 tools)

| Tool | Endpoint | Purpose |
|---|---|---|
| `list_therapists` | GET /api/therapists | List available therapists |
| `book_therapy` | POST /api/therapy/book | Book therapy session (supports MPESA/PAYSTACK/COUPON) |
| `cancel_therapy` | POST /api/therapy/cancel/[id] | Cancel a session |

### 💰 BUDGET & FINANCE (10 tools)

| Tool | Endpoint | Purpose |
|---|---|---|
| `check_budget` | GET /api/budget/settings | View daily/weekly/monthly limits |
| `update_budget` | PUT /api/budget/settings | Update budget limits |
| `budget_categories` | GET /api/budget/categories | View spending categories |
| `savings_goals` | GET /api/budget/goals | List savings goals |
| `create_savings_goal` | POST /api/budget/goals | Create a new savings goal |
| `update_savings_goal` | PUT /api/budget/goals | Update savings goal progress |
| `delete_savings_goal` | DELETE /api/budget/goals | Remove a savings goal |
| `spending_alerts` | GET /api/budget/alerts | View spending alerts |
| `create_alert` | POST /api/budget/alerts | Create a spending alert |
| `financial_journal` | POST /api/budget/journal | Log a financial reflection |

### 🎲 GAMBLING RECOVERY (2 tools)

| Tool | Endpoint | Purpose |
|---|---|---|
| `gambling_assessment` | POST /api/assessments | Take gambling addiction self-assessment |
| `assessment_results` | GET /api/assessments/results | View past assessment results |

### 👥 COMMUNITY CIRCLES (8 tools)

| Tool | Endpoint | Purpose |
|---|---|---|
| `list_circles` | GET /api/circles | List all support circles |
| `join_circle` | POST /api/circles/[id]/join | Join a circle |
| `leave_circle` | DELETE /api/circles/[id]/join | Leave a circle |
| `circle_posts` | GET /api/circles/posts | View posts in a circle |
| `create_post` | POST /api/circles/posts | Share anonymously in a circle |
| `like_post` | POST /api/circles/posts/[id]/like | Like a post |
| `unlike_post` | DELETE /api/circles/posts/[id]/like | Unlike a post |
| `bookmark_post` | POST /api/circles/posts/[id]/bookmark | Bookmark a post |

### 🌱 GARDEN (2 tools)

| Tool | Endpoint | Purpose |
|---|---|---|
| `my_garden` | GET /api/garden/progress | View garden growth data |
| `water_garden` | POST /api/garden/progress | Water garden / daily check-in |

### 💎 SUBSCRIPTIONS (3 tools)

| Tool | Endpoint | Purpose |
|---|---|---|
| `check_subscription` | GET /api/subscription/check | Check premium status |
| `buy_premium` | POST /api/subscription/purchase | Purchase premium via M-Pesa |
| `refresh_subscription` | POST /api/subscription/refresh | Sync subscription after payment |

### 🎁 DONATIONS (4 tools)

| Tool | Endpoint | Purpose |
|---|---|---|
| `make_donation` | POST /api/donations | Donate via M-Pesa STK Push (tracked in SQLite, not self-reported) |
| `donation_history` | GET /api/donations | View donation history |
| `record_donation` | POST http://127.0.0.1:9099/api/donations | Record a donation in MINAKI's SQLite (body: `{phone, amount, source, transaction_id, notes}`) |
| `donation_stats` | GET http://127.0.0.1:9099/api/donations/stats/{phone} | Get aggregated donation statistics for a user |

### 🏷️ COUPONS (2 tools)

| Tool | Endpoint | Purpose |
|---|---|---|
| `validate_coupon` | POST /api/coupons/validate | Check if a coupon is valid |
| `redeem_coupon` | POST /api/coupons/redeem | Redeem a coupon for premium |

### 🔔 NOTIFICATIONS (3 tools)

| Tool | Endpoint | Purpose |
|---|---|---|
| `my_notifications` | GET /api/notifications | View notifications |
| `mark_read` | PATCH /api/notifications/[id] | Mark notification as read |
| `mark_all_read` | POST /api/notifications/mark-all-read | Mark all notifications as read |

### 👤 USER PROFILE (2 tools)

| Tool | Endpoint | Purpose |
|---|---|---|
| `my_profile` | GET /api/user/role | Get user role and info |
| `sync_user` | POST /api/user/sync | Sync user data |

---

## Additional Tools

### 🌐 WEB SEARCH (1 tool)

| Tool | Invocation | Purpose | Source |
|---|---|---|---|
| `web_search` | `python3 /root/.openclaw/workspace/web-search --max N "query"` | Search the web via DuckDuckGo (free, no API key required) | `/root/.openclaw/workspace/web-search` |

### 📤 PROACTIVE OUTBOUND (2 tools)

| Tool | Invocation | Purpose | Auth |
|---|---|---|---|
| `stale_users` | `curl -s -L -X GET "${BASE_URL}/api/users/stale?days=N&limit=M" -H "X-API-Key: ${API_KEY}"` | Get users who haven't interacted in N+ days (includes last mood, crisis flags, name) | API key only (no X-User-Phone needed) |
| `log_outbound` | `curl -s -L -X POST "${BASE_URL}/api/outbound/log" -H "X-API-Key: ${API_KEY}" -H "Content-Type: application/json" -d '{"phone":"...","content":"...","status":"sent"}'` | Log that a proactive message was sent (prevents re-messaging) | API key only (no X-User-Phone needed) |

**Usage Notes:**
- `stale_users` uses `hasValidApiKey()` auth — no `X-User-Phone` header needed
- `log_outbound` also uses API key only auth — no `X-User-Phone` header needed
- Response format for `stale_users`: `{ "users": [{ "phone", "name", "daysSinceLastMessage", "lastMood", "hadCrisisFlag" }], "total", "page", "limit" }`
- These tools are used during **heartbeats** (Section 12 of AGENTS.md) to find and message users who need check-ins
- See `skills/minaki/SKILL.md` Section 17 for full curl command reference

**Usage:**
```bash
# Basic search (5 results)
python3 /root/.openclaw/workspace/web-search "mental health programs in Kenya"

# Custom result count
python3 /root/.openclaw/workspace/web-search --max 3 "gambling addiction help Nairobi"
```

**Returns JSON:** Array of `{title, url, snippet}` objects. Parse the output to extract search results.

**Limitations:**
- Rate-limited by DuckDuckGo (approx. 1 request per second)
- Returns max 20 results per query
- No image or video search — text only
- Requires internet connectivity to the DuckDuckGo API

---

## Configuration Notes

- All requests use the `X-API-Key` and `X-User-Phone` headers for authentication.
- New phone numbers are auto-created as users with ID format `phone_2547XXXXXXXX`.
- The API follows Vercel redirects — always use the `-L` flag with curl.
- Rate limits: 5 requests per 5 minutes for M-Pesa operations.

## Quick Reference: Most Common Workflows

### Daily Check-In Flow
1. Ask mood rating → `mood_assess`
2. Ask about emotions/triggers → `mood_assess` (enriched)
3. Ask about gambling urges → `water_garden` (with `hasGamblingUrge` flag)
4. Celebrate streak → based on response data
5. Suggest next action → journal, meditation, or therapy

### Therapy Booking Flow
1. `list_therapists` → show options
2. Ask for choice → show available slots
3. Ask for date/time → `book_therapy`
4. Ask about payment → offer M-Pesa/Paystack/Coupon
5. Confirm booking → celebration message

### Urge Support Flow
1. Acknowledge the urge → validate feelings
2. Assess strength (1-10) → track it
3. Offer grounding/breathing → guide them through it
4. Log to garden → `water_garden` with `hasGamblingUrge: true`
5. Check savings goals for motivation → `savings_goals`
6. Offer to join Gambling Recovery circle → `list_circles`

📝 TOOLS.md — Available Tools

📜 Version History