Customer_Gateway/api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add readme and .env files

Browse Source
This commit is contained in:
Edwin Eames
2026-01-17 15:41:05 -05:00
parent b93d41c1ae
commit a5a76743c7
5 changed files with 466 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

299
README.md
View File

@@ -1 +1,298 @@
# API
# Auburn Oil Customer Gateway - API
A modern, high-performance REST API powering the Auburn Oil customer self-service portal. Built with FastAPI and designed for reliability, security, and ease of deployment.
```
___ __ ____ _ __
/ | __ __/ /_ __ ___________ / __ \(_) /
/ /| |/ / / / __ \/ / / / ___/ __ \ / / / / / /
/ ___ / /_/ / /_/ / /_/ / / / / / / / /_/ / / /
/_/ |_\__,_/_.___/\__,_/_/ /_/ /_/ \____/_/_/
Customer Gateway API
```
## What This Does
This API serves as the backbone for Auburn Oil's customer portal, enabling:
| Feature | Description |
|---------|-------------|
| **Customer Onboarding** | Multi-step registration for new customers with tank photo uploads |
| **Order Management** | Place heating oil delivery orders with real-time pricing |
| **Payment Processing** | Secure credit card handling via Authorize.net (PCI-compliant) |
| **Account Management** | Password reset, profile updates, delivery history |
| **Tank Inspections** | Upload and manage annual tank inspection photos |
## Tech Stack
- **Framework**: FastAPI 0.104 (async Python)
- **Database**: PostgreSQL with SQLAlchemy 2.0 (async)
- **Authentication**: JWT tokens with bcrypt password hashing
- **Payments**: Authorize.net CIM (tokenized card storage)
- **Server**: Uvicorn ASGI
## Quick Start
### Prerequisites
- Docker & Docker Compose
- PostgreSQL database (can be remote)
- Authorize.net merchant account (sandbox for development)
### 1. Configure Environment
Copy the example environment file and customize:
```bash
cp .env.example .env.dev
```
Edit `.env.dev` with your settings:
```env
# Database
POSTGRES_SERVER=your-db-host
POSTGRES_PORT=5432
POSTGRES_DBNAME=auburnoil
POSTGRES_USERNAME=postgres
POSTGRES_PASSWORD=your-secure-password
# Security (generate a strong key!)
JWT_SECRET_KEY=your-256-bit-secret-key
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=1440
# Payments (use sandbox credentials for dev)
AUTH_NET_API_LOGIN_ID=your-login-id
AUTH_NET_TRANSACTION_KEY=your-transaction-key
# Email (for password resets)
SMTP_SERVER=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_FROM_EMAIL=noreply@yourdomain.com
# Frontend URL (for password reset links)
FRONTEND_URL=http://localhost:3000
```
### 2. Deploy with Docker
**Development** (with hot-reload):
```bash
cd deploy
docker compose -f docker-compose.dev.yml up --build
```
**Local Network Testing**:
```bash
cd deploy
docker compose -f docker-compose.local.yml up --build
```
**Production**:
```bash
cd deploy
docker compose -f docker-compose.prod.yml up -d --build
```
### 3. Access the API
| Environment | API URL | Docs |
|-------------|---------|------|
| Development | http://localhost:8000 | http://localhost:8000/docs |
| Production | https://api.portal.auburnoil.com | https://api.portal.auburnoil.com/docs |
## API Endpoints
### Authentication (`/auth`)
| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/auth/login` | Login with email/password, returns JWT |
| `POST` | `/auth/register` | Register existing customer (requires account #) |
| `POST` | `/auth/new` | New customer single-step registration |
| `POST` | `/auth/step1` | New customer wizard - Step 1 (info) |
| `POST` | `/auth/step2` | New customer wizard - Step 2 (credentials) |
| `POST` | `/auth/step3` | New customer wizard - Step 3 (tank photos) |
| `GET` | `/auth/me` | Get current user profile |
| `POST` | `/auth/forgot-password` | Request password reset email |
| `POST` | `/auth/reset-password` | Complete password reset |
| `POST` | `/auth/change-password` | Change password (authenticated) |
| `POST` | `/auth/upload-tank-images` | Upload tank inspection photos |
| `GET` | `/auth/tank-images/{account}` | Get tank image history |
### Orders (`/order`)
| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/order/` | Place new delivery order (min 100 gallons) |
### Customer Info (`/info`)
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/info/deliveries` | Get delivery history (last 20) |
| `GET` | `/info/pricing/current` | Get current oil price per gallon |
### Payments (`/payment`)
| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/payment/process` | Process payment (saved or new card) |
| `GET` | `/payment/cards` | List saved payment methods |
| `POST` | `/payment/cards` | Save new card (tokenize) |
| `PUT` | `/payment/cards/{id}` | Update card details |
| `DELETE` | `/payment/cards/{id}` | Remove saved card |
| `POST` | `/payment/cards/{id}/set-default` | Set default payment method |
| `POST` | `/payment/sync-billing-info` | Sync billing to Authorize.net |
## Database Setup
### Run Migrations
Apply database migrations in order:
```bash
# Connect to your PostgreSQL database
psql -h your-host -U postgres -d auburnoil
# Run migrations
\i migrations/20240108_create_portal_user_table.sql
\i migrations/20240108_add_tank_image_upload_dates.sql
```
### Key Tables
| Table | Purpose |
|-------|---------|
| `customer_customer` | Customer profiles and addresses |
| `portal_user` | Portal login credentials |
| `delivery_delivery` | Delivery orders and history |
| `card_card` | Saved payment methods (tokenized) |
| `transactions` | Payment transaction records |
| `customer_tank` | Tank inspection metadata |
| `pricing_oil_oil` | Daily oil pricing |
## Project Structure
```
api/
├── main.py # FastAPI app entry point
├── config.py # Environment configuration
├── database.py # Database connection (async)
├── models.py # SQLAlchemy ORM models
├── schemas.py # Pydantic request/response schemas
├── routers/
│ ├── auth.py # Authentication endpoints
│ ├── info.py # Customer info endpoints
│ ├── order.py # Order management
│ └── payment.py # Payment processing
├── services/
│ └── authorizenet.py # Authorize.net integration
├── .env.example # Environment template
├── .env.dev # Development config
├── .env.local # Local network config
├── .env.prod # Production config
├── Dockerfile.dev # Development container
├── Dockerfile.local # Local network container
├── Dockerfile.prod # Production container
└── requirements.txt # Python dependencies
```
## Security Features
- **JWT Authentication**: Stateless token-based auth with configurable expiration
- **Password Hashing**: bcrypt with automatic truncation for compatibility
- **PCI Compliance**: Card data never stored locally (Authorize.net tokenization)
- **Image Sanitization**: Uploaded images resized, metadata stripped
- **CORS Protection**: Environment-specific allowed origins
- **Input Validation**: Pydantic schemas validate all inputs
## Environment Variables Reference
| Variable | Required | Description |
|----------|----------|-------------|
| `MODE` | Yes | `DEVELOPMENT`, `LOCAL`, or `PRODUCTION` |
| `POSTGRES_SERVER` | Yes | Database host |
| `POSTGRES_PORT` | Yes | Database port (usually 5432) |
| `POSTGRES_DBNAME` | Yes | Database name |
| `POSTGRES_USERNAME` | Yes | Database user |
| `POSTGRES_PASSWORD` | Yes | Database password |
| `JWT_SECRET_KEY` | Yes | Secret for signing tokens (use 256+ bits) |
| `JWT_ALGORITHM` | Yes | Algorithm (HS256 recommended) |
| `JWT_ACCESS_TOKEN_EXPIRE_MINUTES` | Yes | Token lifetime in minutes |
| `AUTH_NET_API_LOGIN_ID` | Yes | Authorize.net API Login ID |
| `AUTH_NET_TRANSACTION_KEY` | Yes | Authorize.net Transaction Key |
| `SMTP_SERVER` | Yes | SMTP server for emails |
| `SMTP_PORT` | Yes | SMTP port (587 for TLS) |
| `SMTP_USERNAME` | Yes | SMTP username |
| `SMTP_PASSWORD` | Yes | SMTP password/app password |
| `SMTP_FROM_EMAIL` | Yes | From address for emails |
| `FRONTEND_URL` | Yes | Frontend URL for reset links |
## Troubleshooting
### Common Issues
**Database connection failed**
```
Check POSTGRES_* environment variables
Ensure database is accessible from Docker network
Verify firewall allows connections on port 5432
```
**JWT token invalid**
```
Ensure JWT_SECRET_KEY is the same across restarts
Check token hasn't expired
Verify JWT_ALGORITHM matches what was used to sign
```
**Authorize.net errors**
```
Sandbox vs Production: Use correct credentials for each
Test cards: Use Authorize.net test card numbers in sandbox
Check API Login ID and Transaction Key are correct
```
**Image upload fails**
```
Max file size: 20MB per image
Supported formats: JPEG, PNG
Check /images volume is mounted correctly
```
## Development
### Running Locally (without Docker)
```bash
# Create virtual environment
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Set environment variables
export MODE=DEVELOPMENT
# ... set other variables
# Run with hot-reload
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```
### API Documentation
FastAPI auto-generates interactive documentation:
- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc
- **OpenAPI JSON**: http://localhost:8000/openapi.json
---
**Auburn Oil Customer Gateway** - Built with reliability in mind for New Hampshire and Massachusetts heating oil customers.