docs: add comprehensive API endpoint documentation

[jezweb]

Overview

This PR adds complete API reference documentation that was previously missing from the project.

What's New

New File: docs/API_ENDPOINTS.md (872 lines)

A comprehensive API reference covering the entire application surface:

📡 REST API Endpoints (2)

1. POST /api/summarize

   • Text summarization using Cloudflare Workers AI
   • Configurable length, style, and language
   • Request/response schemas with validation rules

2. /api/auth/[...all]

   • Better Auth endpoints (sign-up, sign-in, sign-out, session)
   • OAuth provider configuration (Google)

⚡ Server Actions (11)

Authentication (3)

• signIn() - Email/password authentication
• signUp() - User registration
• signOut() - Session termination

Todos (6)

• getAllTodos() - Fetch user's todos with categories
• getTodoById() - Fetch single todo
• createTodoAction() - Create with optional R2 image upload
• updateTodoAction() - Full todo update
• updateTodoFieldAction() - Partial update (optimized)
• deleteTodoAction() - Delete todo

Categories (2)

• getAllCategories() - Fetch user's categories
• createCategory() - Create new category

📚 Additional Documentation

Authentication Details

• Better Auth configuration
• OAuth provider setup
• Utility functions (getCurrentUser, requireAuth, isAuthenticated, getSession)

Data Models

• Todo schema with validation rules
• Category schema
• User/AuthUser types
• Session structure

Error Handling

• API error format standards
• Server action error patterns
• Authentication error handling
• Security considerations

Development Patterns

• Revalidation strategy
• Redirect patterns for form actions
• Image upload flow (FormData → R2)

What Each Entry Includes

For every endpoint/action, the documentation provides:

• ✅ Purpose (concise description)
• ✅ Request format with TypeScript types
• ✅ Response format with examples
• ✅ Authentication requirements
• ✅ Error conditions and status codes
• ✅ Practical usage examples
• ✅ Side effects (cache revalidation, redirects, R2 uploads)

Why This Matters

Before: Developers had to read source code to understand the API
After: Complete reference for building features or integrations

This documentation:

• Helps new developers onboard faster
• Serves as a contract for API behavior
• Makes it easier to build external integrations
• Documents security and validation requirements
• Explains Next.js patterns (server actions, revalidation, redirects)

Example Documentation Quality

Here's a sample entry structure:

### createTodoAction()

Purpose: Create a new todo with optional image upload

Request:
- formData: FormData
  - title: string (required)
  - description?: string
  - image?: File (PNG/JPG, max 5MB)
  - categoryId?: number
  - priority: 'low' | 'medium' | 'high' | 'urgent'
  - status: 'pending' | 'in-progress' | 'completed' | 'archived'

Response: Redirects to /dashboard/todos

Side Effects:
- Uploads image to R2 (if provided)
- Revalidates todo list cache
- Redirects on success

Errors:
- Throws authentication error if not logged in
- Re-throws NEXT_REDIRECT for proper redirect handling

Impact

This PR fills a major documentation gap in the project. Developers can now:

• Understand all available endpoints without reading code
• Know exact request/response formats
• See authentication requirements upfront
• Find usage examples for common operations

🤖 Generated with Claude Code

[coderabbitai]

Warning

Rate limit exceeded

@jezweb has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 22 minutes and 11 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between a44687a and fa233f3.

📒 Files selected for processing (1)

• docs/API_ENDPOINTS.md (1 hunks)

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}