WHATSAPP BOT V22 - NAYAPAY GMAIL RECEIPT PARSER + DIAGNOSTICS
==========================================================

THE PROBLEM
BILL -> customer chooses partial amount -> sends proof -> pending, although
regular wallet top-ups may still work. The live reason CANNOT be confirmed
from an offline code ZIP; Gmail API and live NayaPay receiving receipts must
be inspected on your own hosting account.

CODE GAPS FOUND
1) HTML table fields were stripped together, e.g. "Amount ReceivedPKR 200",
   preventing safe parsing of labeled received amount / source account name.
2) Gmail message bodies stored under attachmentId instead of body.data were
   not read by the earlier email parser.
3) Gmail search scanned only 50 messages from a fixed rolling 2-day window.
   V22 searches from request creation and paginates up to 300 hits.
4) Admin had no way to distinguish 'email not delivered' from a parsing,
   authentication, date, amount or sender-name mismatch.

CHANGED FILES (NO DATABASE MIGRATION)
 bot.shoaibsubscription.pk/nayapay_topup.php
 bot.shoaibsubscription.pk/adminpanel/nayapay_topups.php
 bot.shoaibsubscription.pk/adminpanel/nayapay_review.php
 bot.shoaibsubscription.pk/adminpanel/nayapay_diagnostics.php   (NEW)
 bot.shoaibsubscription.pk/cron/nayapay_diagnose.php           (NEW)

INSTALL
1. Backup your existing website files and MySQL database first.
2. Upload V22_CHANGED_ONLY.zip into the PARENT folder that contains
   bot.shoaibsubscription.pk and extract, preserving folder structure.
3. Overwrite existing files when asked; do NOT delete any files.
4. Do NOT replace OAuth tokens or Gmail credentials: this ZIP contains NONE.
5. No .sql import needed.

HOW TO FIND EXACT FAILURE STAGE
1. Open https://bot.shoaibsubscription.pk/adminpanel/nayapay_topups.php
2. Open the affected pending Credit Bill row.
3. Click "Gmail Diagnostics" then "Check Connected Gmail & Receipt".
   The diagnostic is READ ONLY and never settles a payment.
4. Look at:
   - Gmail connected status + configured receiving mailbox
   - Gmail search + total emails listed since payment request
   - email body read / authentication pass
   - parsed sender and labeled amount
   - rejection stage: authentication, sender, amount, date, already used
   - other Gmail messages mentioning NayaPay (different sender)
5. Share a screenshot of the diagnostic RESULT excluding personal financial
   or sensitive data. DO NOT share OAuth tokens, database passwords, or full
   bank account details.

CLI ALTERNATIVE
  php /home/YOUR_CPANEL_USER/public_html/bot.shoaibsubscription.pk/cron/nayapay_diagnose.php PAYMENT_ID

RESULT GUIDE
  gmail_not_connected: wrong Gmail or OAuth token file expired.
  gmail_api_error: Google permission, OAuth or networking failure.
  listed=0: no receipt from configured sender within payment time window;
    inspect the other NayaPay email sender list and actual receiving inbox.
  receipt_before_request: email delivered before payment request began.
  authentication_not_verified: email found but sender proof cannot be verified;
    DO NOT auto-credit; manually verify from NayaPay bank history.
  receipt_amount_not_parsed: body extracted but received amount label differs.
  sender_name_mismatch: screenshot sender not same as receiving bank receipt.
  amount_mismatch: request and actual receipt amounts differ.
  receipt_already_used: duplicate, already credited Gmail receipt.
  receipt_eligible: matching candidate exists. Customer can send CHECK.

CREDIT PAYMENT SAFETY
- A screenshot is NOT proof that money arrived in your account.
- Only a fresh unused authenticated NayaPay email receipt with the exact
  source name and received amount may settle the customer's ledger.
- Do not mark status='paid' directly in SQL; that skips ledger accounting.
- Use existing admin "Manually Verify" only after actual bank confirmation;
  "Already Recorded" closes old requests without double credit.
- Existing customer wallet top-up flow remains separate.

TESTING
- PHP syntax checked all changed PHP files.
- Unit tests passed for HTML receipt parsing, decoded attached Gmail text,
  exact amount/sender requirements, Gmail search and sender authentication.
- NOT tested against live Gmail/NayaPay or production MySQL.
- First test with one small real payment and check diagnostics if pending.
