Skip to content

API Documentation

Jump to bottom
Dinesh Dawonauth edited this page Jul 22, 2025 · 1 revision

Complete reference for My Progress Planner REST API endpoints.

🔗 Base URL

Development: http://localhost:3000/api
Production: https://your-domain.com/api

🔐 Authentication

Most endpoints require user authentication via Supabase JWT tokens.

Headers

Authorization: Bearer <supabase_jwt_token>
Content-Type: application/json

Response Format

All API responses follow this consistent structure:

interface APIResponse<T> {
  data: T | null;
  error: string | null;
  meta?: {
    total?: number;
    page?: number;
    limit?: number;
  };
}

📊 Core Endpoints

🍽️ Meals API

Get Today's Meals

GET /api/meals/today

Response:

{
  "data": {
    "breakfast": {
      "id": "uuid",
      "content": "Oatmeal with berries",
      "ai_response": "What a nutritious start to your day! 💕",
      "logged_at": "2025-01-15T08:30:00Z"
    },
    "lunch": null,
    "dinner": null
  },
  "error": null
}

Log a Meal

POST /api/meals/log

Request Body:

{
  "mealType": "breakfast" | "lunch" | "dinner",
  "content": "Scrambled eggs with toast"
}

Response:

{
  "data": {
    "meal": {
      "id": "uuid",
      "content": "Scrambled eggs with toast",
      "ai_response": "Perfect protein to fuel your morning! 🌟",
      "logged_at": "2025-01-15T08:30:00Z"
    }
  },
  "error": null
}

Check Meal Status

GET /api/meals/check?type=breakfast

Response:

{
  "data": {
    "exists": true,
    "content": "Oatmeal with berries",
    "logged_at": "2025-01-15T08:30:00Z"
  },
  "error": null
}

🔥 Streak API

Get Current Streak

GET /api/streak

Response:

{
  "data": {
    "current_streak": 7,
    "best_streak": 14,
    "streak_start_date": "2025-01-08",
    "total_days": 45
  },
  "error": null
}

📋 Summaries API

Get Daily Summaries

GET /api/summaries?page=1&limit=10

Response:

{
  "data": [
    {
      "id": "uuid",
      "summary_date": "2025-01-15",
      "content": "You had an amazing day with all three meals logged! 🎉",
      "meals_count": 3,
      "created_at": "2025-01-15T23:00:00Z"
    }
  ],
  "meta": {
    "total": 25,
    "page": 1,
    "limit": 10
  },
  "error": null
}

Get Specific Summary

GET /api/summaries/2025-01-15

Response:

{
  "data": {
    "summary_date": "2025-01-15",
    "content": "You had an amazing day with all three meals logged! 🎉",
    "meals_count": 3,
    "meals": [
      {
        "meal_type": "breakfast",
        "content": "Oatmeal with berries",
        "logged_at": "2025-01-15T08:30:00Z"
      }
    ]
  },
  "error": null
}

🤖 AI Integration

Generate AI Response

POST /api/ai/chat

Request Body:

{
  "mealType": "breakfast",
  "content": "Greek yogurt with granola",
  "context": {
    "streak": 5,
    "previousMeals": [],
    "timeOfDay": "morning"
  }
}

Response:

{
  "data": {
    "response": "Greek yogurt with granola sounds absolutely delicious! 💕",
    "metadata": {
      "tokens_used": 45,
      "model": "gpt-4",
      "response_time_ms": 1250
    }
  },
  "error": null
}

Get Daily Quote

GET /api/ai/quote

Response:

{
  "data": {
    "quote": "Every meal is an opportunity to nourish yourself with love! 💕",
    "cached": true
  },
  "error": null
}

👤 User API

Get User Profile

GET /api/user/profile

Response:

{
  "data": {
    "id": "uuid",
    "name": "John Doe",
    "email": "[email protected]",
    "friend_code": "LOVE123",
    "created_at": "2025-01-01T00:00:00Z"
  },
  "error": null
}

Update User Name

PUT /api/user/name

Request Body:

{
  "name": "John Smith"
}

Get Friend Code

GET /api/user/friend-code

Response:

{
  "data": {
    "friend_code": "LOVE123"
  },
  "error": null
}

👥 Friends API

Search Friends

GET /api/friends/search?code=LOVE456

Response:

{
  "data": {
    "user": {
      "name": "Jane Doe",
      "friend_code": "LOVE456"
    }
  },
  "error": null
}

Get Friends List

GET /api/friends

Response:

{
  "data": [
    {
      "friend_code": "LOVE456",
      "name": "Jane Doe",
      "added_at": "2025-01-10T00:00:00Z"
    }
  ],
  "error": null
}

🔔 Push Notifications

Subscribe to Notifications

POST /api/notifications/subscribe

Request Body:

{
  "subscription": {
    "endpoint": "https://fcm.googleapis.com/fcm/send/...",
    "keys": {
      "p256dh": "key_data",
      "auth": "auth_data"
    }
  }
}

Send Test Notification

POST /api/notifications/test

⚙️ Admin API

Note: Requires admin authentication via ADMIN_PASSWORD

Get System Stats

GET /api/admin/stats

Headers:

Authorization: Bearer <admin_password>

Response:

{
  "data": {
    "total_users": 1250,
    "total_meals": 15680,
    "active_users_today": 245,
    "meals_today": 892,
    "avg_streak": 5.2
  },
  "error": null
}

Get All Summaries

GET /api/admin/summaries

Manual Meal Log (Testing)

POST /api/admin/log-meal

Request Body:

{
  "userId": "user_uuid",
  "mealType": "breakfast",
  "content": "Test meal for debugging"
}

🔄 Cron Jobs

Automated Meal Reminders

Lunch Reminder

GET /api/cron/lunch
  • Schedule: Daily at 6:00 PM UTC (18:00)
  • Purpose: Send lunch logging reminders

Dinner Reminder

GET /api/cron/dinner
  • Schedule: Daily at 1:00 AM UTC (01:00)
  • Purpose: Send dinner logging reminders

Authentication:

Authorization: Bearer <CRON_SECRET>

📊 Error Codes

Code Message Description
400 Bad Request Invalid request data
401 Unauthorized Missing or invalid authentication
403 Forbidden Insufficient permissions
404 Not Found Resource doesn't exist
409 Conflict Meal already logged for this type/date
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server-side error

Example Error Response

{
  "data": null,
  "error": "Meal already logged for breakfast today"
}

🔒 Rate Limiting

  • General API: 100 requests/hour per user
  • AI Endpoints: 20 requests/hour per user
  • Admin Endpoints: 200 requests/hour per IP

🧪 Testing

Using curl

# Get today's meals
curl -H "Authorization: Bearer YOUR_JWT" \
     https://your-domain.com/api/meals/today

# Log a meal
curl -X POST \
     -H "Authorization: Bearer YOUR_JWT" \
     -H "Content-Type: application/json" \
     -d '{"mealType":"breakfast","content":"Pancakes"}' \
     https://your-domain.com/api/meals/log

Using JavaScript/TypeScript

// Utility function for API calls
async function apiCall<T>(endpoint: string, options?: RequestInit): Promise<T> {
  const response = await fetch(`/api${endpoint}`, {
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
      ...options?.headers,
    },
    ...options,
  });

  return response.json();
}

// Example usage
const meals = await apiCall('/meals/today');
const result = await apiCall('/meals/log', {
  method: 'POST',
  body: JSON.stringify({
    mealType: 'breakfast',
    content: 'Oatmeal with berries'
  })
});

🔄 Webhooks (Future Feature)

Planned webhook endpoints for external integrations:

  • POST /api/webhooks/meal-logged - Triggered when meal is logged
  • POST /api/webhooks/streak-milestone - Triggered on streak milestones
  • POST /api/webhooks/summary-generated - Triggered when daily summary is created

📱 PWA API Integration

Service Worker Cache Strategy

  • Cache First: /api/ai/quote, /api/user/name
  • Network First: /api/meals/log, /api/ai/chat
  • Stale While Revalidate: /api/meals/check, /api/streak

Background Sync

Failed API calls are queued and retried when connection is restored:

  • Meal logging
  • AI response generation
  • User profile updates

📞 Support

Clone this wiki locally