# WhatsApp OTP Authentication Setup & Flow

## 1. Overview
This system provides WhatsApp-based OTP verification for Customer Login and Registration. It replaces traditional SMS delivery with WhatsApp, aiming for higher deliverability and potentially lower costs.
Currently, it supports a `dummy` mode for local development and testing, and is structured as "live-ready" to easily integrate a real WhatsApp Business API provider later.

## 2. Customer OTP Flow

### Login Flow
1. Customer enters their 10-digit mobile number on the OTP Sign-in page.
2. System checks if the mobile number belongs to an active registered customer.
3. If valid, an OTP is generated, hashed, and stored in `customer_otps` table.
4. OTP is sent via WhatsApp (or logged if in dummy mode).
5. Customer enters the 6-digit OTP within the 5-minute expiry window.
6. System verifies the OTP hash and checks for max attempts limits.
7. Upon success, a Sanctum token is returned and the user is logged in.

### Register Flow
1. Customer enters details including mobile number on the Registration page.
2. Customer clicks "Verify via WhatsApp".
3. System ensures the mobile is not already registered.
4. OTP is generated, hashed, sent, and verified similar to the login flow.
5. Once verified, the registration form submission includes an `otp_verified=true` flag (or similar logic) to finalize account creation.

## 3. Dummy vs Live-Ready Mode

### Dummy Mode (`OTP_MODE=dummy`)
- Does not make real external HTTP API calls.
- Generates a real OTP and securely hashes it.
- **Action:** Writes the generated OTP directly to `storage/logs/laravel.log`.
- **Testing Number:** Specifically for the number `8518822685`, testing tools or Postman will receive a success response. (DO NOT expose actual OTP in production JSON responses).

### Live Mode (`OTP_MODE=live`)
- Triggers the real HTTP request via `WhatsAppOtpService` to your WhatsApp API provider.

## 4. Configuration Requirements
Add the following to your `.env` file:

```env
# OTP Core Settings
OTP_CHANNEL=whatsapp
OTP_MODE=dummy
OTP_EXPIRY_MINUTES=5
OTP_RESEND_SECONDS=60
OTP_MAX_ATTEMPTS=5

# WhatsApp Provider Details
WHATSAPP_BRAND_NAME="Mangalore Stores"
WHATSAPP_TEST_PHONE=8518822685

WHATSAPP_PROVIDER=dummy # Change to meta, twilio, etc., later
WHATSAPP_API_BASE_URL=
WHATSAPP_API_TOKEN=
WHATSAPP_PHONE_NUMBER_ID=
WHATSAPP_TEMPLATE_NAME=otp_verification
WHATSAPP_TEMPLATE_LANGUAGE=en
```

**Where to Change Testing Number:**
Update `WHATSAPP_TEST_PHONE=8518822685` in `.env`.

**Where to Set Company Name:**
Update `APP_NAME="Mangalore Stores"` and `WHATSAPP_BRAND_NAME="Mangalore Stores"` in `.env`.
*Important Note:* The sender name that appears on the customer's WhatsApp application is configured directly in the WhatsApp Business Manager / API Provider dashboard (Display Name). It cannot be dynamically hidden or changed via this codebase. This code only injects the brand name into the message body.

## 5. Security Rules
- **No Plaintext OTPs:** OTPs are stored using `Hash::make()` in the database.
- **Expiry:** OTPs strictly expire in `OTP_EXPIRY_MINUTES` (5 mins).
- **Brute Force Protection:** Maximum of `OTP_MAX_ATTEMPTS` (5) wrong entries allowed before the OTP is invalidated.
- **Rate Limiting:** A 60-second cooldown is enforced before the user can request a resend.
- **Single Use:** Verified OTPs cannot be reused.

## 6. Integration Files
- **Backend Services:** `app/Services/OtpService.php`, `app/Services/WhatsAppOtpService.php`
- **Controllers:** `app/Http/Controllers/Api/Customer/CustomerOtpController.php`
- **Frontend JS:** `public/common/js/customer/otpsignin.js`, `public/common/js/customer/register.js`
- **Database Table:** `customer_otps`

## 7. Future Real WhatsApp Provider Integration Steps
When ready to go live with a real provider (e.g., Meta Cloud API):
1. Change `OTP_MODE=live` and `WHATSAPP_PROVIDER=meta` in `.env`.
2. Fill in `WHATSAPP_API_BASE_URL`, `WHATSAPP_API_TOKEN`, and `WHATSAPP_PHONE_NUMBER_ID` in `.env`.
3. Open `app/Services/WhatsAppOtpService.php` and uncomment/implement the HTTP logic in the `sendMetaCloudApi` method (or create a new method for your specific provider).
4. Ensure your WhatsApp Template (`WHATSAPP_TEMPLATE_NAME`) is approved in the Meta dashboard with the correct variable structure (e.g., `{{1}}` for OTP, `{{2}}` for Minutes).