diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..7866dbe --- /dev/null +++ b/docs/api.md @@ -0,0 +1,1239 @@ +# Personal System API Documentation + +## Overview + +This API serves a personal productivity system with habit tracking and intake metrics. The system supports three client types: +- **TUI (Terminal User Interface)**: Command-line interface for quick interactions +- **Mobile App**: Native mobile application for on-the-go tracking +- **Web Application**: Rich web interface with analytics and reporting + +## Base URL + +``` +Production: https://api.personal-system.com/v1 +Development: http://localhost:3000/api/v1 +``` + +## Authentication + +All endpoints require authentication via JWT tokens passed in the Authorization header: + +``` +Authorization: Bearer +``` + +### Authentication Endpoints + +#### Login +```http +POST /auth/login +``` + +**Request Body:** +```json +{ + "email": "user@example.com", + "password": "securepassword" +} +``` + +**Response:** +```json +{ + "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", + "user": { + "id": "user-uuid", + "username": "johndoe", + "email": "user@example.com" + }, + "expires_at": "2024-01-15T12:00:00Z" +} +``` + +#### Refresh Token +```http +POST /auth/refresh +``` + +**Request Body:** +```json +{ + "refresh_token": "refresh_token_here" +} +``` + +#### Logout +```http +POST /auth/logout +``` + +## Common Patterns + +### Pagination +List endpoints support pagination with the following parameters: +- `limit`: Number of items per page (default: 50, max: 100) +- `offset`: Number of items to skip (default: 0) +- `cursor`: Cursor-based pagination for real-time data + +**Example:** +```http +GET /api/habits?limit=20&offset=40 +``` + +### Filtering +Most endpoints support filtering via query parameters: +- `fields`: Select specific fields to return +- `active`: Filter by active status (true/false) +- `start_date`: Filter by start date (ISO 8601) +- `end_date`: Filter by end date (ISO 8601) + +**Example:** +```http +GET /api/habits?fields=id,name,active&active=true +``` + +### Response Format +All responses follow this structure: +```json +{ + "data": [], // or {} for single items + "meta": { + "total": 100, + "limit": 20, + "offset": 40, + "has_more": true + }, + "links": { + "self": "/api/habits?limit=20&offset=40", + "next": "/api/habits?limit=20&offset=60", + "prev": "/api/habits?limit=20&offset=20" + } +} +``` + +## Error Handling + +### Error Response Format +```json +{ + "error": { + "code": "VALIDATION_ERROR", + "message": "Invalid request parameters", + "details": [ + { + "field": "target_count", + "message": "Must be a positive integer" + } + ], + "request_id": "req-uuid" + } +} +``` + +### HTTP Status Codes +- `200 OK`: Success +- `201 Created`: Resource created successfully +- `400 Bad Request`: Invalid request parameters +- `401 Unauthorized`: Authentication required +- `403 Forbidden`: Insufficient permissions +- `404 Not Found`: Resource not found +- `409 Conflict`: Resource already exists +- `422 Unprocessable Entity`: Validation error +- `429 Too Many Requests`: Rate limit exceeded +- `500 Internal Server Error`: Server error + +## Rate Limiting + +Rate limits are enforced per client type: +- **TUI**: 100 requests per minute +- **Mobile**: 200 requests per minute +- **Web**: 300 requests per minute + +Rate limit headers are included in all responses: +```http +X-RateLimit-Limit: 100 +X-RateLimit-Remaining: 95 +X-RateLimit-Reset: 1642262400 +``` + +## Caching + +### ETags +Most GET endpoints support ETags for efficient caching: +```http +ETag: "33a64df551" +``` + +Use the `If-None-Match` header to check for updates: +```http +If-None-Match: "33a64df551" +``` + +### Cache Headers +```http +Cache-Control: max-age=300, private +Last-Modified: Mon, 15 Jan 2024 10:00:00 GMT +``` + +--- + +# Habits API + +## Core Endpoints + +### List Habits +```http +GET /api/habits +``` + +**Query Parameters:** +- `active`: Filter by active status (true/false) +- `frequency_type`: Filter by frequency type (daily/interval/multi_daily) +- `fields`: Select specific fields +- `limit`, `offset`: Pagination + +**Response:** +```json +{ + "data": [ + { + "id": "habit-uuid", + "name": "Take vitamins", + "description": "Daily vitamin supplement", + "frequency_type": "daily", + "target_count": 1, + "interval_days": null, + "active": true, + "created_at": "2024-01-01T00:00:00Z", + "updated_at": "2024-01-01T00:00:00Z" + } + ], + "meta": { + "total": 5, + "limit": 50, + "offset": 0, + "has_more": false + } +} +``` + +### Get Habit +```http +GET /api/habits/{habit_id} +``` + +**Response:** +```json +{ + "data": { + "id": "habit-uuid", + "name": "Take vitamins", + "description": "Daily vitamin supplement", + "frequency_type": "daily", + "target_count": 1, + "interval_days": null, + "active": true, + "created_at": "2024-01-01T00:00:00Z", + "updated_at": "2024-01-01T00:00:00Z" + } +} +``` + +### Create Habit +```http +POST /api/habits +``` + +**Request Body:** +```json +{ + "name": "Morning meditation", + "description": "15 minutes of mindfulness", + "frequency_type": "daily", + "target_count": 1 +} +``` + +**Response:** `201 Created` with the created habit object. + +### Update Habit +```http +PUT /api/habits/{habit_id} +``` + +**Request Body:** +```json +{ + "name": "Updated habit name", + "description": "Updated description", + "active": false +} +``` + +### Delete Habit +```http +DELETE /api/habits/{habit_id} +``` + +**Response:** `204 No Content` + +## Habit Completions + +### List Completions +```http +GET /api/habits/{habit_id}/completions +``` + +**Query Parameters:** +- `start_date`: ISO 8601 date +- `end_date`: ISO 8601 date +- `limit`, `offset`: Pagination + +**Response:** +```json +{ + "data": [ + { + "id": "completion-uuid", + "habit_id": "habit-uuid", + "completed_at": "2024-01-15T08:30:00Z", + "notes": "Completed during lunch break", + "created_at": "2024-01-15T08:30:00Z" + } + ], + "meta": { + "total": 30, + "limit": 50, + "offset": 0, + "has_more": false + } +} +``` + +### Create Completion +```http +POST /api/habits/{habit_id}/completions +``` + +**Request Body:** +```json +{ + "completed_at": "2024-01-15T08:30:00Z", + "notes": "Completed during lunch break" +} +``` + +**Response:** `201 Created` with the completion object. + +### Bulk Create Completions +```http +POST /api/habits/completions/bulk +``` + +**Request Body:** +```json +{ + "completions": [ + { + "habit_id": "habit-uuid-1", + "completed_at": "2024-01-15T08:30:00Z", + "notes": "Morning habit" + }, + { + "habit_id": "habit-uuid-2", + "completed_at": "2024-01-15T09:00:00Z" + } + ] +} +``` + +## Habit Status + +### Get Habit Status +```http +GET /api/habits/{habit_id}/status +``` + +**Response:** +```json +{ + "data": { + "habit_id": "habit-uuid", + "completed_today": true, + "completions_today": 2, + "target_count": 2, + "completion_rate": 1.0, + "current_streak": 15, + "longest_streak": 30, + "next_due_date": null, + "last_completed_at": "2024-01-15T08:30:00Z", + "status": "completed" + } +} +``` + +### Get All Habits Status +```http +GET /api/habits/status +``` + +**Response:** +```json +{ + "data": [ + { + "habit_id": "habit-uuid", + "name": "Take vitamins", + "completed_today": true, + "completions_today": 1, + "target_count": 1, + "status": "completed" + } + ] +} +``` + +### Bulk Status Check +```http +POST /api/habits/status/bulk +``` + +**Request Body:** +```json +{ + "habit_ids": ["habit-uuid-1", "habit-uuid-2"] +} +``` + +## Habit Analytics + +### Get Habit Statistics +```http +GET /api/habits/{habit_id}/stats +``` + +**Query Parameters:** +- `period`: week/month/year (default: month) +- `start_date`: ISO 8601 date +- `end_date`: ISO 8601 date + +**Response:** +```json +{ + "data": { + "habit_id": "habit-uuid", + "period": "month", + "start_date": "2024-01-01", + "end_date": "2024-01-31", + "total_completions": 28, + "total_days": 31, + "completion_rate": 0.9032, + "current_streak": 15, + "longest_streak": 20, + "average_completions_per_day": 1.2, + "daily_breakdown": [ + { + "date": "2024-01-01", + "completions": 1, + "target_met": true + } + ] + } +} +``` + +### Get Habit Calendar +```http +GET /api/habits/calendar +``` + +**Query Parameters:** +- `start_date`: ISO 8601 date +- `end_date`: ISO 8601 date +- `habit_ids`: Comma-separated list of habit IDs + +**Response:** +```json +{ + "data": { + "start_date": "2024-01-01", + "end_date": "2024-01-31", + "habits": [ + { + "habit_id": "habit-uuid", + "name": "Take vitamins", + "calendar_data": [ + { + "date": "2024-01-01", + "completions": 1, + "target_met": true, + "status": "completed" + } + ] + } + ] + } +} +``` + +### Get Dashboard +```http +GET /api/habits/dashboard +``` + +**Response:** +```json +{ + "data": { + "overview": { + "total_habits": 5, + "active_habits": 4, + "completed_today": 3, + "completion_rate_today": 0.75, + "current_streak_avg": 12.5 + }, + "habits": [ + { + "habit_id": "habit-uuid", + "name": "Take vitamins", + "frequency_type": "daily", + "completed_today": true, + "completions_today": 1, + "target_count": 1, + "current_streak": 15, + "status": "completed" + } + ], + "upcoming": [ + { + "habit_id": "habit-uuid", + "name": "Weekly cleaning", + "next_due_date": "2024-01-20", + "days_until_due": 3 + } + ] + } +} +``` + +--- + +# Intake Tracker API + +## Intake Metrics + +### List Intake Metrics +```http +GET /api/intake/metrics +``` + +**Query Parameters:** +- `active`: Filter by active status (true/false) +- `is_cumulative`: Filter by cumulative type (true/false) +- `fields`: Select specific fields + +**Response:** +```json +{ + "data": [ + { + "id": "metric-uuid", + "metric_type": "water", + "unit": "ml", + "display_name": "Water Intake", + "target_value": 2000, + "min_value": null, + "max_value": null, + "is_cumulative": true, + "active": true, + "created_at": "2024-01-01T00:00:00Z", + "updated_at": "2024-01-01T00:00:00Z" + } + ], + "meta": { + "total": 3, + "limit": 50, + "offset": 0, + "has_more": false + } +} +``` + +### Get Intake Metric +```http +GET /api/intake/metrics/{metric_id} +``` + +### Create Intake Metric +```http +POST /api/intake/metrics +``` + +**Request Body:** +```json +{ + "metric_type": "water", + "unit": "ml", + "display_name": "Water Intake", + "target_value": 2000, + "is_cumulative": true +} +``` + +### Update Intake Metric +```http +PUT /api/intake/metrics/{metric_id} +``` + +### Delete Intake Metric +```http +DELETE /api/intake/metrics/{metric_id} +``` + +## Intake Records + +### List Intake Records +```http +GET /api/intake/metrics/{metric_id}/records +``` + +**Query Parameters:** +- `start_date`: ISO 8601 date +- `end_date`: ISO 8601 date +- `limit`, `offset`: Pagination + +**Response:** +```json +{ + "data": [ + { + "id": "record-uuid", + "intake_metric_id": "metric-uuid", + "value": 500, + "recorded_at": "2024-01-15T08:30:00Z", + "notes": "Morning hydration", + "created_at": "2024-01-15T08:30:00Z" + } + ], + "meta": { + "total": 8, + "limit": 50, + "offset": 0, + "has_more": false + } +} +``` + +### Create Intake Record +```http +POST /api/intake/metrics/{metric_id}/records +``` + +**Request Body:** +```json +{ + "value": 500, + "recorded_at": "2024-01-15T08:30:00Z", + "notes": "Morning hydration" +} +``` + +### Bulk Create Records +```http +POST /api/intake/records/bulk +``` + +**Request Body:** +```json +{ + "records": [ + { + "intake_metric_id": "metric-uuid-1", + "value": 500, + "recorded_at": "2024-01-15T08:30:00Z", + "notes": "Morning water" + }, + { + "intake_metric_id": "metric-uuid-2", + "value": 70.5, + "recorded_at": "2024-01-15T07:00:00Z" + } + ] +} +``` + +## Intake Progress + +### Get Metric Progress +```http +GET /api/intake/metrics/{metric_id}/progress +``` + +**Query Parameters:** +- `date`: Specific date (default: today) + +**Response:** +```json +{ + "data": { + "metric_id": "metric-uuid", + "date": "2024-01-15", + "current_value": 1500, + "target_value": 2000, + "unit": "ml", + "percentage_complete": 75, + "status": "in_progress", + "remaining": 500, + "entries_count": 3, + "first_entry_at": "2024-01-15T07:00:00Z", + "last_entry_at": "2024-01-15T14:30:00Z" + } +} +``` + +### Get All Metrics Progress +```http +GET /api/intake/progress +``` + +**Response:** +```json +{ + "data": [ + { + "metric_id": "metric-uuid", + "metric_type": "water", + "display_name": "Water Intake", + "current_value": 1500, + "target_value": 2000, + "unit": "ml", + "percentage_complete": 75, + "status": "in_progress" + } + ] +} +``` + +## Intake Analytics + +### Get Daily Summaries +```http +GET /api/intake/metrics/{metric_id}/summaries +``` + +**Query Parameters:** +- `start_date`: ISO 8601 date +- `end_date`: ISO 8601 date +- `period`: day/week/month (default: day) + +**Response:** +```json +{ + "data": [ + { + "id": "summary-uuid", + "intake_metric_id": "metric-uuid", + "date": "2024-01-15", + "total_value": 2100, + "entry_count": 4, + "first_entry_at": "2024-01-15T07:00:00Z", + "last_entry_at": "2024-01-15T20:00:00Z", + "target_met": true, + "target_value": 2000 + } + ] +} +``` + +### Get Intake Trends +```http +GET /api/intake/metrics/{metric_id}/trends +``` + +**Query Parameters:** +- `period`: week/month/year (default: month) +- `start_date`: ISO 8601 date +- `end_date`: ISO 8601 date + +**Response:** +```json +{ + "data": { + "metric_id": "metric-uuid", + "period": "month", + "start_date": "2024-01-01", + "end_date": "2024-01-31", + "average_daily_value": 1850, + "target_value": 2000, + "target_achievement_rate": 0.85, + "highest_value": 2500, + "lowest_value": 1200, + "total_entries": 124, + "daily_data": [ + { + "date": "2024-01-01", + "value": 1800, + "target_met": false, + "entry_count": 4 + } + ] + } +} +``` + +### Get Intake Calendar +```http +GET /api/intake/calendar +``` + +**Query Parameters:** +- `start_date`: ISO 8601 date +- `end_date`: ISO 8601 date +- `metric_ids`: Comma-separated list of metric IDs + +**Response:** +```json +{ + "data": { + "start_date": "2024-01-01", + "end_date": "2024-01-31", + "metrics": [ + { + "metric_id": "metric-uuid", + "display_name": "Water Intake", + "unit": "ml", + "calendar_data": [ + { + "date": "2024-01-01", + "value": 1800, + "target_value": 2000, + "target_met": false, + "entry_count": 4 + } + ] + } + ] + } +} +``` + +### Get Dashboard +```http +GET /api/intake/dashboard +``` + +**Response:** +```json +{ + "data": { + "overview": { + "total_metrics": 3, + "active_metrics": 3, + "targets_met_today": 2, + "target_achievement_rate": 0.67 + }, + "metrics": [ + { + "metric_id": "metric-uuid", + "display_name": "Water Intake", + "current_value": 1500, + "target_value": 2000, + "unit": "ml", + "percentage_complete": 75, + "status": "in_progress", + "entries_today": 3 + } + ] + } +} +``` + +--- + +# Cross-System Integration + +## Unified Dashboard +```http +GET /api/dashboard +``` + +**Response:** +```json +{ + "data": { + "overview": { + "date": "2024-01-15", + "habits_completed": 3, + "habits_total": 4, + "intake_targets_met": 2, + "intake_targets_total": 3 + }, + "habits": { + "completed_today": 3, + "completion_rate": 0.75, + "current_streak_avg": 12.5, + "habits": [ + { + "habit_id": "habit-uuid", + "name": "Take vitamins", + "status": "completed", + "completions_today": 1, + "target_count": 1 + } + ] + }, + "intake": { + "targets_met": 2, + "target_achievement_rate": 0.67, + "metrics": [ + { + "metric_id": "metric-uuid", + "display_name": "Water Intake", + "current_value": 1500, + "target_value": 2000, + "status": "in_progress" + } + ] + } + } +} +``` + +## Goal Integration + +### List Goal-Linked Habits +```http +GET /api/goals/habits +``` + +**Response:** +```json +{ + "data": [ + { + "habit_id": "habit-uuid", + "name": "Drink enough water", + "goal_type": "water", + "goal_target": 2000, + "goal_unit": "ml", + "linked_metric_id": "metric-uuid", + "auto_complete": true, + "status": "pending" + } + ] +} +``` + +### Get Goal Status +```http +GET /api/goals/status +``` + +**Response:** +```json +{ + "data": [ + { + "habit_id": "habit-uuid", + "name": "Drink enough water", + "goal_target": 2000, + "current_intake": 1500, + "goal_progress": 0.75, + "goal_met": false, + "habit_completed": false, + "can_auto_complete": false + } + ] +} +``` + +## Reports + +### Weekly Report +```http +GET /api/reports/weekly +``` + +**Query Parameters:** +- `start_date`: ISO 8601 date (default: start of current week) + +**Response:** +```json +{ + "data": { + "period": "week", + "start_date": "2024-01-08", + "end_date": "2024-01-14", + "habits": { + "total_habits": 4, + "average_completion_rate": 0.82, + "best_habit": { + "name": "Take vitamins", + "completion_rate": 1.0 + }, + "needs_attention": [ + { + "name": "Exercise", + "completion_rate": 0.57 + } + ] + }, + "intake": { + "total_metrics": 3, + "average_target_achievement": 0.75, + "best_metric": { + "display_name": "Water Intake", + "achievement_rate": 0.86 + } + } + } +} +``` + +### Monthly Report +```http +GET /api/reports/monthly +``` + +--- + +# Real-Time Features + +## WebSocket Connection + +### Connect to WebSocket +``` +wss://api.personal-system.com/v1/ws?token= +``` + +### WebSocket Events + +#### Subscribe to Events +```json +{ + "type": "subscribe", + "channels": ["habits", "intake", "dashboard"] +} +``` + +#### Habit Completion Event +```json +{ + "type": "habit_completed", + "data": { + "habit_id": "habit-uuid", + "completion_id": "completion-uuid", + "completed_at": "2024-01-15T08:30:00Z" + } +} +``` + +#### Intake Record Event +```json +{ + "type": "intake_recorded", + "data": { + "metric_id": "metric-uuid", + "record_id": "record-uuid", + "value": 500, + "recorded_at": "2024-01-15T08:30:00Z" + } +} +``` + +#### Goal Achievement Event +```json +{ + "type": "goal_achieved", + "data": { + "habit_id": "habit-uuid", + "metric_id": "metric-uuid", + "goal_target": 2000, + "current_value": 2000, + "auto_completed": true + } +} +``` + +## Push Notifications + +### Register Device Token +```http +POST /api/notifications/devices +``` + +**Request Body:** +```json +{ + "token": "device_token_here", + "platform": "ios", + "app_version": "1.0.0" +} +``` + +### Update Notification Settings +```http +PUT /api/notifications/settings +``` + +**Request Body:** +```json +{ + "habit_reminders": true, + "goal_achievements": true, + "daily_summary": true, + "weekly_report": true +} +``` + +--- + +# Client-Specific Optimizations + +## TUI Client + +### Compact Endpoints +Use the `compact=true` query parameter for minimal data transfer: + +```http +GET /api/habits/status?compact=true +``` + +**Response:** +```json +{ + "data": [ + { + "id": "habit-uuid", + "name": "Take vitamins", + "status": "completed" + } + ] +} +``` + +### Terminal-Friendly Format +Use the `format=terminal` query parameter for structured output: + +```http +GET /api/habits/dashboard?format=terminal +``` + +## Mobile Client + +### Offline Sync +```http +GET /api/sync/changes?since= +``` + +**Response:** +```json +{ + "data": { + "habits": { + "created": [], + "updated": [], + "deleted": [] + }, + "completions": { + "created": [], + "updated": [], + "deleted": [] + }, + "intake_records": { + "created": [], + "updated": [], + "deleted": [] + } + }, + "sync_timestamp": "2024-01-15T12:00:00Z" +} +``` + +### Quick Actions +```http +POST /api/quick/habit-complete/{habit_id} +``` + +```http +POST /api/quick/intake-record/{metric_id} +``` + +## Web Client + +### Bulk Operations +```http +POST /api/bulk/operations +``` + +**Request Body:** +```json +{ + "operations": [ + { + "type": "habit_complete", + "habit_id": "habit-uuid" + }, + { + "type": "intake_record", + "metric_id": "metric-uuid", + "value": 500 + } + ] +} +``` + +### Export Data +```http +GET /api/export/habits?format=csv&start_date=2024-01-01&end_date=2024-01-31 +``` + +```http +GET /api/export/intake?format=json&metric_ids=metric-uuid-1,metric-uuid-2 +``` + +--- + +# SDK and Integration + +## Webhook Support + +### Register Webhook +```http +POST /api/webhooks +``` + +**Request Body:** +```json +{ + "url": "https://your-app.com/webhook", + "events": ["habit_completed", "goal_achieved"], + "secret": "webhook_secret" +} +``` + +### Webhook Payload +```json +{ + "event": "habit_completed", + "data": { + "habit_id": "habit-uuid", + "completion_id": "completion-uuid", + "completed_at": "2024-01-15T08:30:00Z" + }, + "timestamp": "2024-01-15T08:30:00Z", + "signature": "sha256=..." +} +``` + +## API Versioning + +The API uses URL-based versioning: +- Current version: `/v1/` +- Future versions: `/v2/`, `/v3/`, etc. + +Version deprecation notices will be provided via the `X-API-Version-Deprecated` header. + +--- + +This API documentation provides comprehensive coverage of all endpoints for the personal productivity system, optimized for TUI, mobile, and web clients. \ No newline at end of file