# WhatsApp Commerce Hub

The WhatsApp Commerce Hub is an automated chat commerce platform that bridges WooCommerce online stores with WhatsApp. It enables merchants to automate customer shopping journeys, product browsing, cart management, checkout, and payments directly inside WhatsApp, while synchronizing all order and product data with their WooCommerce store.

## Features

- **Automated Shopping Journey**: Guide customers through a step-by-step chat flow to browse products, add items to their cart, and complete orders.
- **WooCommerce Synchronization**: Bi-directional sync of products, categories, stock levels, and order statuses.
- **PesePay Payment Integration**: Support local Zimbabwean payment options (EcoCash, OneMoney, Visa, Mastercard) via Pesepay gateway with automated payment links and status polling.
- **Meta WhatsApp Cloud API Integration**: Direct link to client WhatsApp Business accounts, enabling official messaging templates, interactive list replies, and quick buttons.
- **Dashboard Control Panel**: An administrative console for merchants to configure integrations, view chat history logs, manage active sessions, track orders, and sync products.

## Technology Stack

### Backend
- **Framework**: NestJS (TypeScript)
- **Database**: PostgreSQL (Prisma ORM)
- **APIs**: Meta Graph API (v19.0), Paynow API, WooCommerce REST API
- **Authentication**: Passport.js with JWT Strategy

### Frontend
- **Framework**: Next.js (TypeScript, Turbopack)
- **Styling**: Tailwind CSS
- **Icons**: Lucide React

---

## Project Structure

```text
whatsapp-commerce-hub/
├── backend/            # NestJS Application
│   ├── prisma/         # Prisma Schema & Database Migrations
│   └── src/            # NestJS Source Code (auth, business, commerce, whatsapp, payments)
├── frontend/           # Next.js Application
│   ├── public/         # Static assets
│   └── src/            # Next.js Source Code (app router, components, contexts)
└── docker-compose.yml  # Docker Compose Configuration for Database/Services
```

---

## Prerequisites

- Node.js (v20 or higher)
- npm (v10 or higher)
- PostgreSQL database (running locally or via Docker)
- ngrok (or similar tunnel service) for local webhook testing

---

## Installation and Setup

### 1. Database Setup
If using Docker, start the PostgreSQL container using the included configuration:
```bash
docker-compose up -d
```

### 2. Backend Configuration
Navigate to the backend directory:
```bash
cd backend
```

Create a `.env` file (copied from `.env.example` if available) and configure the environment variables:
```env
PORT=3001
DATABASE_URL="postgresql://postgres:secretpassword@localhost:5432/whatsapp_commerce?schema=public"
JWT_SECRET="your-secure-jwt-secret"
ENCRYPTION_KEY="your-32-character-hex-encryption-key"
WHATSAPP_VERIFY_TOKEN="whatsapp-verify-token"
```

Run database migrations and seed default data:
```bash
npx prisma migrate dev
npx prisma db seed
```

Start the backend application in development mode:
```bash
npm run start:dev
```

### 3. Frontend Configuration
Navigate to the frontend directory:
```bash
cd ../frontend
```

Create a `.env.local` file:
```env
NEXT_PUBLIC_API_URL=http://localhost:3001
```

Start the frontend application in development mode:
```bash
npm run dev
```

---

## WhatsApp Cloud API Integration

To route live messages from WhatsApp to your local development server:

1. **Expose Local Server (Tunneling)**: Expose your NestJS backend (listening on port 3001) to the public internet using one of the following methods:

   * **Option A: Using Localtunnel (Zero-install)**
     ```bash
     npx localtunnel --port 3001
     ```

   * **Option B: Using Ngrok**
     ```bash
     ngrok http 3001
     ```

2. **Configure Meta Webhook**:
   - Access your App Dashboard on the Meta Developer Console.
   - Set the **Callback URL** to `https://<your-tunnel-subdomain>/webhooks/whatsapp` (e.g. `https://xxxx.ngrok-free.app/webhooks/whatsapp` or `https://xxxx.localtunnel.me/webhooks/whatsapp`).
   - Set the **Verify Token** to `whatsapp-verify-token` (matching your backend env variable).
   - Under **Webhook Fields**, subscribe to **`messages`**.

3. **Configure Integrations in Dashboard**:
   - Navigate to `http://localhost:3000/dashboard/integrations`.
   - Enter your **WABA Phone Number ID** and **Permanent Graph Access Token**.
   - Test the connection and save.

---

## CI/CD Deployment (development branch)

This repository includes a GitHub Actions workflow that builds the backend and frontend and deploys to your development server when commits are pushed to the `development` branch.

- **Workflow file**: `.github/workflows/deploy-development.yml`
- **Deploy script (runs on server)**: `scripts/deploy_dev.sh`

Required GitHub Secrets (Repository → Settings → Secrets):

- `DEV_SERVER_HOST` — server IP or hostname
- `DEV_SERVER_USER` — SSH user (e.g., `ubuntu`)
- `DEV_SERVER_SSH_KEY` — private SSH key (PEM) for the user
- `DEV_SERVER_PORT` — SSH port (default `22`)
- `DEV_SERVER_APP_PATH` — absolute path on the server where the repo is checked out (e.g., `/home/ubuntu/whatsapp-commerce-hub`)
- `NEXT_PUBLIC_API_URL` — public backend URL used at frontend build time (e.g., `https://dev.example.com`)
 - `REPO_CLONE_TOKEN` — personal access token (with `repo` scope) used by the workflow to clone the repository on first bootstrap (kept secret)

Server prerequisites:

- Git must be installed and the application repository cloned at `DEV_SERVER_APP_PATH`.
- Docker and Docker Compose must be installed and usable by the deploy user.
- The deploy user must have permission to run Docker commands (e.g., be in the `docker` group or use sudo without password).

Note: The workflow can now bootstrap a fresh server during the first deploy — it will install Git and Docker (Ubuntu/Debian via `get.docker.com`) and clone the repository using `REPO_CLONE_TOKEN`. Ensure the token has the necessary `repo` scope for private repos.

Manual deploy (SSH into server and run):

```bash
cd /path/to/whatsapp-commerce-hub
chmod +x ./scripts/deploy_dev.sh
./scripts/deploy_dev.sh
```

If you want the workflow to set up the server on first deploy, tell me and I can add bootstrap steps (install Docker, clone repo, etc.).