SHOAIB BOT — WHISKEYSOCKETS BAILEYS / META SEPARATE INTEGRATION
================================================================

What changed
------------
- WA Sender / Zender PHP transport, webhook, admin controls and stored keys removed.
- Old provider settings are sanitized automatically on first code request.
- Visiting the authenticated WhatsApp API Providers page cleans legacy WA Sender PHP files
  left by ZIP merge. The external WA Sender subscription/account is NOT changed.
- The original Meta Cloud API, its callback URL, customer/sales/wallet/billing engine,
  admin panel URLs and database structure remain unchanged.
- New Baileys incoming/outgoing adapter is a SEPARATE Node.js service.

VERY IMPORTANT — THIS IS NOT A FREE HOSTED API
----------------------------------------------
WhiskeySockets/Baileys is a free open-source Node.js library, not a URL where you
paste an API key. Node.js 20+ must run persistently (VPS / supported cPanel Node.js
app / another server). Shared PHP-only hosting alone cannot run this connector.
Baileys is unofficial and may be affected by WhatsApp policy/changes. Hosting can
have costs. Use with consent; avoid unsolicited mass messages.

Install — same server (Node + PHP)
--------------------------------
1. Make a site and database backup; upload/merge entire ZIP into your existing
   bot.shoaibsubscription.pk root. DO NOT delete production data.
2. Keep live storage/bot_runtime.json and live config/database.php, config/meta.php;
   do not replace server secrets with old copies from your ZIP.
3. On server terminal where Node.js >=20 exists:
      cd /path/to/bot.shoaibsubscription.pk/baileys_bridge
      npm install --omit=dev
      cp .env.example .env
4. In adminpanel/whatsapp_api.php click "Generate new secure bridge secret".
   Copy the one-time secret into .env as BRIDGE_SECRET; do not publish it.
5. For same-machine Node + PHP use these .env settings:
      HOST=127.0.0.1
      PORT=8787
      BRIDGE_SECRET=<secret from admin>
      PHP_WEBHOOK_URL=https://bot.shoaibsubscription.pk/webhook/baileys_webhook.php
      BAILEYS_AUTH_DIR=./session
   Make .env private (chmod 600). Keep session folder private and backed up securely.
6. Start Node.js using a supported PROCESS MANAGER (e.g. pm2) or cPanel's
   Node.js application interface. Do not rely on a one-off terminal session:
      node server.mjs
   or use `pm2 start server.mjs --name shoaib-baileys` if installed.
7. Admin > WhatsApp API Providers:
      Enable Baileys, select Baileys as active provider.
      Baileys Bridge URL: http://127.0.0.1:8787
      Secret is already saved from step 4.
   SAVE, refresh QR status, open WhatsApp Settings > Linked Devices > Link a Device,
   scan QR code shown inside the admin panel.
8. Dashboard -> Global Bot ON. From another number send "Menu".
   Then test Prime Video/product, numeric choice, BILL and order flow with TEST data.
9. Start with one small test, verify both inbound and outbound logs.

Separate Node server
--------------------
Host Node on a VPS or other always-on Node server. Put an HTTPS reverse proxy with
valid TLS in front of its local port. Do NOT expose an unauthenticated public Node
service. All bridge API requests use timestamped HMAC shared secret.
Admin Bridge URL = https://your-bridge.example.com (replace with your domain).
PHP_WEBHOOK_URL always points to the existing PHP bot URL above.
Configure the firewall/proxy to permit Node outbound HTTPS to PHP bot and PHP
outbound HTTPS to bridge. The browser itself does NOT need Node credentials.

Receiving/sending architecture
-----------------------------
WhatsApp -> Baileys messages.upsert -> Node bridge signed POST -> PHP
/webhook/baileys_webhook.php -> existing handleIncomingMessage / image handler
-> sendTextMessage() -> Baileys HTTP transport -> Node sock.sendMessage()

Meta uses the unchanged /webhook/webhook.php with its own Meta sender.
Select only ONE active provider; no cross-provider fallback.

Notes & troubleshooting
-----------------------
- No new SQL normally required. New install without webhook_message_dedupe table:
  PHP attempts CREATE TABLE IF NOT EXISTS once. If DB lacks CREATE permission,
  manually run database/baileys_webhook_dedupe_optional.sql (does not erase data).
- Don't deploy old storage/wa_providers.json from an older ZIP over new settings.
  Automatic cleanup discards old third-party key and ID on first request.
- If connection says "bridge_unavailable", check Node process, bridge URL, firewall,
  secret match and SSL; if "scan_qr", scan it; if "connected", test incoming.
- If "php_http_403", shared secret and server time (NTP) are mismatched;
  if "php_http_503", active provider/bot settings are OFF.
- If messages to customers are not recognized (especially @lid), confirm Baileys
  resolves a customer phone number (multi-device LID mappings can vary by version).
- Sending a message ID means Node/WhatsApp accepted a send attempt; it does not
  necessarily prove delivery or read receipts.
- Incoming image screenshots up to 8MB supported, saved under protected storage.
- Never send production API credentials or QR content to other people.

Offline validation
------------------
Node syntax and PHP syntax can be checked without connecting to a WhatsApp account.
A real end-to-end integration test requires your own hosting Node process, an
actual QR scan, a connected WhatsApp device and the production MySQL database.
