# API Validation Guide

## Login Endpoint: POST `/api/auth/login`

### Required Fields

The following fields are **required** and will throw an error if missing:

- ✅ `clerk_user_id` - Clerk user identifier
- ✅ `email` - User email address

### Optional Fields

- `user_type` - Type of user (direct_client, agency, subaccount)
- `first_name` - User's first name
- `last_name` - User's last name
- `full_name` - User's full name (maps to `name` in database)
- `image_url` - User's profile image URL
- `ghl_agency_id` - GoHighLevel agency ID
- `ghl_subaccount_id` - GoHighLevel subaccount ID

### Request Example

```javascript
// ✅ Valid Request
const response = await axios.post("http://localhost:5000/api/auth/login", {
  clerk_user_id: "user_2abc123xyz",  // REQUIRED
  email: "john@example.com",          // REQUIRED
  user_type: "direct_client",
  first_name: "John",
  last_name: "Doe",
  full_name: "John Doe",
  image_url: "https://img.clerk.com/abc123"
});
```

### Error Responses

#### Missing `clerk_user_id`

```json
{
  "success": false,
  "message": "clerk_user_id is required"
}
```

#### Missing `email`

```json
{
  "success": false,
  "message": "email is required"
}
```

### Success Response

```json
{
  "success": true,
  "message": "Login successful",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "account_id": 1,
      "email": "john@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "image_url": "https://img.clerk.com/abc123",
      "role": "owner",
      "created_at": "2025-11-20T12:00:00.000Z",
      "last_login_at": "2025-11-20T13:30:00.000Z"
    },
    "account": {
      "id": 1,
      "user_type": "direct_client",
      "name": "John Doe",
      "email": "john@example.com",
      "clerk_user_id": "user_2abc123xyz"
    },
    "user_type": "direct_client",
    "redirect_url": "/dashboard"
  }
}
```

## Frontend Integration

### React + Clerk Example

```javascript
import { useUser } from "@clerk/clerk-react";
import axios from "axios";

function LoginHandler() {
  const { user, isSignedIn } = useUser();

  useEffect(() => {
    if (isSignedIn && user) {
      loginToBackend();
    }
  }, [isSignedIn, user]);

  const loginToBackend = async () => {
    try {
      // Ensure required fields are present
      if (!user.id || !user.primaryEmailAddress?.emailAddress) {
        console.error("Missing required Clerk user data");
        return;
      }

      const response = await axios.post("http://localhost:5000/api/auth/login", {
        clerk_user_id: user.id,                                    // REQUIRED
        email: user.primaryEmailAddress?.emailAddress,             // REQUIRED
        user_type: "direct_client",
        first_name: user.firstName,
        last_name: user.lastName,
        full_name: user.fullName,
        image_url: user.imageUrl,
      });

      const { token, user_type } = response.data.data;
      
      localStorage.setItem("token", token);
      localStorage.setItem("user_type", user_type);
      
      // Redirect based on user_type
      if (user_type === "direct_client") {
        navigate("/client/dashboard");
      } else if (user_type === "agency") {
        navigate("/agency/dashboard");
      }
    } catch (error) {
      if (error.response?.data?.message) {
        console.error("Login error:", error.response.data.message);
      } else {
        console.error("Login failed:", error);
      }
    }
  };

  return null;
}
```

## Validation Flow

```
1. Request received → Extract payload
2. Check clerk_user_id → Throw error if missing
3. Check email → Throw error if missing
4. Find existing account by clerk_user_id
5. If not found, find by email
6. Create new account/user OR update existing
7. Issue JWT token
8. Return response with token + user_type
```

## Testing

### cURL Test

```bash
# Valid request
curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "clerk_user_id": "user_test123",
    "email": "test@example.com",
    "user_type": "direct_client",
    "full_name": "Test User"
  }'

# Missing clerk_user_id (should fail)
curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com"
  }'

# Missing email (should fail)
curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "clerk_user_id": "user_test123"
  }'
```

## Summary

✅ **Required Fields**: `clerk_user_id`, `email`  
✅ **Validation**: Throws error if required fields are missing  
✅ **Response**: Returns JWT token + user data + user_type  
✅ **Frontend**: Can redirect based on user_type