# E-Commerce API

A FastAPI-based RESTful API for an e-commerce application with user authentication, product catalog, shopping cart, order processing, and payment processing.

## Features

- User authentication with JWT
- Product catalog with categories
- Shopping cart functionality
- Order management
- Mock payment processing
- Search and filtering products
- Admin and regular user roles

## Technology Stack

- **Framework**: FastAPI
- **Database**: SQLite
- **ORM**: SQLAlchemy
- **Migration Tool**: Alembic
- **Authentication**: JWT with password hashing

## Project Structure

```
ecommerce-api/
├── app/
│   ├── api/
│   │   ├── deps.py
│   │   └── v1/
│   │       ├── api.py
│   │       └── endpoints/
│   │           ├── auth.py
│   │           ├── cart.py
│   │           ├── categories.py
│   │           ├── health.py
│   │           ├── orders.py
│   │           ├── payments.py
│   │           ├── products.py
│   │           └── users.py
│   ├── core/
│   │   ├── config.py
│   │   └── security.py
│   ├── db/
│   │   └── session.py
│   ├── models/
│   │   ├── base.py
│   │   ├── cart.py
│   │   ├── order.py
│   │   ├── product.py
│   │   └── user.py
│   ├── schemas/
│   │   ├── cart.py
│   │   ├── order.py
│   │   ├── product.py
│   │   ├── token.py
│   │   └── user.py
│   └── services/
├── migrations/
│   ├── env.py
│   ├── script.py.mako
│   └── versions/
│       └── 0001_create_tables.py
├── storage/
│   └── db/
├── alembic.ini
├── main.py
└── requirements.txt
```

## Setup and Installation

### 1. Clone the repository

```bash
git clone https://github.com/your-username/ecommerce-api.git
cd ecommerce-api
```

### 2. Create a virtual environment

```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

### 3. Install dependencies

```bash
pip install -r requirements.txt
```

### 4. Set up environment variables

Create a `.env` file in the root directory:

```
JWT_SECRET_KEY=your_secret_key_here
```

### 5. Initialize the database

```bash
alembic upgrade head
```

### 6. Run the application

```bash
uvicorn main:app --reload
```

The API will be available at http://localhost:8000.

## API Documentation

Once the application is running, you can access the API documentation at:

- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

## API Endpoints

### Authentication

- `POST /api/v1/auth/register` - Register a new user with email and password
- `POST /api/v1/auth/login` - Login with email (provided in the username field) and password to get access token

### Users

- `GET /api/v1/users/me` - Get current user information
- `PUT /api/v1/users/me` - Update current user information
- `GET /api/v1/users/{user_id}` - Get user by ID (admin only)
- `GET /api/v1/users/` - List all users (admin only)

### Categories

- `GET /api/v1/categories/` - List all categories
- `POST /api/v1/categories/` - Create a new category (admin only)
- `GET /api/v1/categories/{category_id}` - Get category by ID
- `PUT /api/v1/categories/{category_id}` - Update a category (admin only)
- `DELETE /api/v1/categories/{category_id}` - Delete a category (admin only)

### Products

- `GET /api/v1/products/` - List all products (with filtering options)
- `POST /api/v1/products/` - Create a new product (admin only)
- `GET /api/v1/products/{product_id}` - Get product by ID
- `PUT /api/v1/products/{product_id}` - Update a product (admin only)
- `DELETE /api/v1/products/{product_id}` - Delete a product (admin only)

### Cart

- `GET /api/v1/cart/` - Get user's cart
- `POST /api/v1/cart/items` - Add item to cart
- `PUT /api/v1/cart/items/{item_id}` - Update cart item quantity
- `DELETE /api/v1/cart/items/{item_id}` - Remove item from cart
- `DELETE /api/v1/cart/` - Clear cart

### Orders

- `GET /api/v1/orders/` - List user's orders (admin can see all)
- `POST /api/v1/orders/` - Create a new order from cart
- `GET /api/v1/orders/{order_id}` - Get order by ID
- `PUT /api/v1/orders/{order_id}` - Update order (limited for regular users)
- `DELETE /api/v1/orders/{order_id}` - Cancel order

### Payments

- `POST /api/v1/payments/` - Process payment for an order

### Health Check

- `GET /health` - Application health check
- `GET /api/v1/health/` - Detailed health check

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| JWT_SECRET_KEY | Secret key for JWT token generation | supersecretkey |
| JWT_ALGORITHM | Algorithm used for JWT | HS256 |
| ACCESS_TOKEN_EXPIRE_MINUTES | Token expiration time in minutes | 30 |

## Database

The application uses SQLite as the database. The database file is created at `/app/storage/db/db.sqlite`.

## CORS Configuration

The API has robust CORS (Cross-Origin Resource Sharing) enabled with the following configuration:

- Allowed origins: 
  - http://localhost
  - http://localhost:3000
  - http://127.0.0.1
  - http://127.0.0.1:3000
  - https://v0-ecommerce-app-build-swart.vercel.app
  - https://*.vercel.app (for preview deployments)
  - * (wildcard for development)

- Allowed methods: GET, POST, PUT, DELETE, OPTIONS, PATCH
- Allowed headers: 
  - Authorization
  - Content-Type
  - Accept
  - Accept-Language
  - Content-Language
  - Content-Length
  - Origin
  - X-Requested-With
  - X-CSRF-Token
  - Access-Control-Allow-Origin
  - Access-Control-Allow-Credentials
  - X-HTTP-Method-Override

- Exposed headers: Content-Length, Content-Type, Authorization
- Credentials support: Enabled (supports JWT authentication)
- Max age for preflight requests: 3600 seconds (1 hour)

### Custom CORS Handling

This application implements a custom CORS middleware that properly handles preflight OPTIONS requests for all endpoints, including authentication routes. The middleware includes:

1. Direct handling of OPTIONS requests for all endpoints
2. Proper header handling for preflight responses
3. Explicit support for POST requests with JSON content-type 
4. Full support for Authorization headers for authenticated endpoints
5. Pattern matching for wildcard domains (e.g., *.vercel.app)

### CORS Test Endpoint

The API includes a special endpoint for testing CORS functionality:

- `OPTIONS /api/v1/cors-test` - Test preflight requests
- `POST /api/v1/cors-test` - Test POST requests with JSON body

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| USE_CUSTOM_CORS_ONLY | Whether to use only the custom CORS middleware | True |