Updated README.md

README.md

@@ -1,12 +1,11 @@
-# 3DAI CORE API
+# 3D E-Commerce Backend API
 
-This repository contains a FastAPI-based proxy service that integrates:
+This repository contains a FastAPI backend for a robust 3D model e-commerce platform. It integrates:
 
-- **Meshy Image-to-3D API** (v1) to generate 3D models from images
-- **Meshy Text-to-3D API** (v2) to generate 3D models from text prompts
-- **OpenAI Chat Completion API** to reframe user text into ideal 3D prompts
-
-It also includes a simple `frontend.html` for manual testing of all endpoints.
+- **Supabase** for authentication, user, and credit management
+- **Meshy** for 3D model generation (Image-to-3D, Text-to-3D)
+- **OpenAI** for prompt reframing
+- Endpoints for user onboarding, credit-guarded model generation, credit purchase, order placement, and user dashboard
 
 ---
 
@@ -16,12 +15,15 @@ It also includes a simple `frontend.html` for manual testing of all endpoints.
 - [Installation](#installation)
 - [Configuration](#configuration)
 - [Running Locally](#running-locally)
-- [Docker Deployment (Hugging Face Spaces)](#docker-deployment-hugging-face-spaces)
 - [API Endpoints](#api-endpoints)
+  - [Authentication](#authentication)
+  - [User Onboarding & Profile](#user-onboarding--profile)
+  - [Credits](#credits)
+  - [3D Model Generation](#3d-model-generation)
+  - [Orders](#orders)
+  - [User Dashboard](#user-dashboard)
   - [Health Check](#health-check)
-  - [Image-to-3D](#image-to-3d)
-  - [Text-to-3D](#text-to-3d)
-- [Frontend Testing UI](#frontend-testing-ui)
+- [References](#references)
 
 ---
 
@@ -29,7 +31,8 @@ It also includes a simple `frontend.html` for manual testing of all endpoints.
 
 - Python 3.10+
 - `pip`
-- Docker (for containerized deployment)
+- Supabase project (with tables: User, User_Credit_Account, Generated_Models, Model_Order_History, Credit_Order_History)
+- Meshy and OpenAI API keys
 
 ---
 
@@ -37,10 +40,9 @@ It also includes a simple `frontend.html` for manual testing of all endpoints.
 
 ```bash
 git clone <your-repo-url>
-cd <repo-folder>
-python -m venv .venv   # optional but recommended
-source .venv/bin/activate
-pip install --upgrade pip
+cd api-backend
+python -m venv venv
+source venv/bin/activate
 pip install -r requirements.txt
 ```
 
@@ -48,166 +50,159 @@ pip install -r requirements.txt
 
 ## Configuration
 
-Create a `.env` file in the project root with:
+Create a `.env` file in the project root:
 
 ```ini
+SUPABASE_URL=https://<your-supabase>.supabase.co
+SUPABASE_KEY=<your-supabase-service-role-key>
 MESHY_API_KEY=msy_<your_meshy_key>
 OPENAI_API_KEY=sk-<your_openai_key>
 ```
 
-- `MESHY_API_KEY`: your API key from Meshy ([Image-to-3D docs](https://docs.meshy.ai/en/api/image-to-3d), [Text-to-3D docs](https://docs.meshy.ai/en/api/text-to-3d)).
-- `OPENAI_API_KEY`: your OpenAI key for the Chat Completion endpoint.
-
 ---
 
 ## Running Locally
 
-Start the FastAPI server on port 8000:
-
 ```bash
-export MESHY_API_KEY=msy_...
-export OPENAI_API_KEY=sk-...
+export SUPABASE_URL=...
+export SUPABASE_KEY=...
+export MESHY_API_KEY=...
+export OPENAI_API_KEY=...
 python main.py
 ```
 
 - Swagger UI: http://127.0.0.1:8000/docs
-- ReDoc: http://127.0.0.1:8000/redoc
-
----
-
-## Docker Deployment (Hugging Face Spaces)
-
-This service is containerized for HF Spaces on port **7860**.
-
-1. Commit `Dockerfile` as-is.
-2. Push to your HF Space repository.
-3. In Spaces UI, set repository secrets:
-   - `MESHY_API_KEY`
-   - `OPENAI_API_KEY`
-4. Space will auto-build and serve at `https://<your-space>.hf.space`.
 
 ---
 
 ## API Endpoints
 
-### Health Check
+### Authentication
 
-- **URL**: `/`
-- **Method**: `GET`
+- **POST `/auth/signup`**  
+  Sign up a new user.  
+  **Body:** `{ "email": "...", "password": "..." }`
 
-**Response**
+- **POST `/auth/signin`**  
+  Sign in and receive JWT.  
+  **Body:** `{ "email": "...", "password": "..." }`  
+  **Response:** `{ "access_token": "...", "user": {...} }`
 
-```json
-{ "status": "ok" }
-```
+- **POST `/auth/complete-profile`**  
+  Complete user profile and initialize credits.  
+  **Auth:** Bearer token  
+  **Body:** `{ "address": "...", "fullname": "...", "phone_number": "..." }`
 
 ---
 
-### Image-to-3D
+### User Onboarding & Profile
 
-#### 1) Create Task
+- **GET `/user/profile`**  
+  Get current user's profile.  
+  **Auth:** Bearer token
 
-- **URL**: `/req-img-to-3d`
-- **Method**: `POST`
-- **Auth**: `Authorization: Bearer <MESHY_API_KEY>`
-- **Content-Type**: `multipart/form-data`
-- **Body**:
-  - `image` (file, `.jpg|.png`)
+---
 
-**Response** (201)
+### Credits
 
-```json
-{ "result": "<task_id>" }
-```
+- **GET `/user/credits`**  
+  Get available generation credits.  
+  **Auth:** Bearer token
 
-#### 2) Retrieve Task
+- **POST `/credits/purchase`**  
+  Purchase credits, updates credit account and order history.  
+  **Auth:** Bearer token  
+  **Body:**  
+  ```json
+  {
+    "number_of_generations": 10,
+    "price": 19.99,
+    "transaction_id": "txn_123"
+  }
+  ```
 
-- **URL**: `/req-result-img-to-3d/{task_id}`
-- **Method**: `GET`
-- **Auth**: `Authorization: Bearer <MESHY_API_KEY>`
+---
 
-**Response** (200)
+### 3D Model Generation
 
-```json
-{
-  "id": "...",
-  "model_urls": { "glb": "...", "obj": "...", ... },
-  "thumbnail_url": "...",
-  "progress": 100,
-  "status": "SUCCEEDED",
-  ...
-}
-```
+- **POST `/req-img-to-3d`**  
+  Generate 3D model from image (costs 1 credit).  
+  **Auth:** Bearer token  
+  **Body:** `multipart/form-data` with `image` file
 
-#### 3) List Tasks
+- **GET `/req-result-img-to-3d/{task_id}`**  
+  Get status/result of image-to-3D task.  
+  **Auth:** Bearer token
 
-- **URL**: `/list-img-to-3d-req`
-- **Method**: `GET`
-- **Auth**: `Authorization: Bearer <MESHY_API_KEY>`
+- **GET `/list-img-to-3d-req`**  
+  List all image-to-3D tasks for user.  
+  **Auth:** Bearer token
 
-**Response**
+- **POST `/req-text-to-3d`**  
+  Generate 3D model from text (costs 1 credit, prompt reframed by OpenAI).  
+  **Auth:** Bearer token  
+  **Body:** `{ "text": "..." }`
 
-An array or paginated list of Image-to-3D task objects (same schema as retrieve).
+- **GET `/req-result-text-to-3d/{task_id}`**  
+  Get status/result of text-to-3D task.  
+  **Auth:** Bearer token
 
----
+- **GET `/list-text-to-3d-req`**  
+  List all text-to-3D tasks for user.  
+  **Auth:** Bearer token
 
-### Text-to-3D
+---
 
-#### 4) Create Task
+### Orders
 
-- **URL**: `/req-text-to-3d`
-- **Method**: `POST`
-- **Auth**: `Authorization: Bearer <MESHY_API_KEY>`
-- **Content-Type**: `application/json`
-- **Body**:
+- **POST `/orders/place`**  
+  Place an order for a 3D model print.  
+  **Auth:** Bearer token  
+  **Body:**  
   ```json
-  { "text": "Describe your object..." }
+  {
+    "generated_model_id": "...",
+    "price": 29.99,
+    "packaging_price": 5.00,
+    "material_price": 10.00,
+    "delivery_address": "...",
+    "order_status": "pending",
+    "estimated_delivery_date": "2024-07-01",
+    "shipping_tracking_id": "track_123",
+    "payment_status": "paid",
+    "transaction_id": "txn_456"
+  }
   ```
 
-**Behavior**:
-1. Sends user text to OpenAI Chat Completion to reframe prompt.
-2. Calls Meshy `/openapi/v2/text-to-3d` with `{ mode: "preview", prompt: <reframed> }`.
-
-**Response** (200)
-
-```json
-{ "result": "<task_id>" }
-```
-
-#### 5) Retrieve Task
+- **GET `/user/orders`**  
+  Get all orders for the current user.  
+  **Auth:** Bearer token
 
-- **URL**: `/req-result-text-to-3d/{task_id}`
-- **Method**: `GET`
-- **Auth**: `Authorization: Bearer <MESHY_API_KEY>`
-
-**Response**
+---
 
-Full Text-to-3D Task Object (schema matches Image-to-3D with additional fields: `prompt`, `mode`, `video_url`, etc.)
+### User Dashboard
 
-#### 6) List Tasks
+- **GET `/user/models`**  
+  Get all generated models for the current user.  
+  **Auth:** Bearer token
 
-- **URL**: `/list-text-to-3d-req`
-- **Method**: `GET`
-- **Auth**: `Authorization: Bearer <MESHY_API_KEY>`
+---
 
-**Response**
+### Health Check
 
-Array of Text-to-3D Task Objects.
+- **GET `/`**  
+  Returns `{ "status": "ok" }`
 
 ---
 
-## Frontend Testing UI
-
-Open `frontend.html` in a browser (or serve via simple HTTP). It provides sections for:
+## References
 
-1. **Setting HF Spaces Token** (for private deployment)
-2. **Image-to-3D** create, retrieve, list
-3. **Text-to-3D** create, retrieve, list
+- [Supabase Docs](https://supabase.com/docs)
+- [Meshy Image-to-3D API](https://docs.meshy.ai/en/api/image-to-3d)
+- [Meshy Text-to-3D API](https://docs.meshy.ai/en/api/text-to-3d)
+- [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat/create)
 
-Enter your Hugging Face token in step 0, then test each API live.
 ---
 
-## References
-- Meshy Image-to-3D API docs: https://docs.meshy.ai/en/api/image-to-3d
-- Meshy Text-to-3D API docs: https://docs.meshy.ai/en/api/text-to-3d
-- OpenAI Chat Completion API: https://platform.openai.com/docs/api-reference/chat/create
+**Note:** All endpoints requiring authentication expect a Bearer token in the `Authorization` header.  
+**Credit-guarded endpoints** will decrement user credits atomically and return an error if insufficient.