HOME AVENUE ORDERS - Koombiyo order tool
=========================================

SETUP (about 10 minutes)
1. In cPanel, create a subdomain or folder, e.g. orders.yourdomain.lk
   (needs HTTPS. Use AutoSSL / Let's Encrypt in cPanel.)
2. Upload all files in this zip to that folder. Keep the data/ folder and the .htaccess files.
3. Make sure the data/ folder is writable (permission 755, owned by your cPanel user).
4. Copy config.sample.php to config.php and fill in:
   - KB_API_KEY and KB_PASSWORD  (Koombiyo portal > Profile Settings > API KEY > Create)
   - APP_PASSWORD                (password for opening the order page)
   - WEBHOOK_KEY                 (any random text, e.g. h7k2m9x4q1)
   - DEFAULT_LABEL_FORMAT        (A6, THERMAL, POD or DOT)
5. Open the site, log in, click "Load cities from Koombiyo" once.
6. In Koombiyo portal > Profile Settings > Add Client Webhook, enter:
     https://orders.yourdomain.lk/webhook.php?key=YOUR_WEBHOOK_KEY
   Then use "Trigger Webhook Test" there to check it.
7. CONNECT GOOGLE SHEET (products, stock, orders)
   a. Open your Home_Avenue_Purchases Google Sheet > Extensions > Apps Script.
   b. Delete what's there, paste everything from google-apps-script.gs.
   c. On the first line change TOKEN to a random text. Put the same text in config.php as SHEET_TOKEN.
   d. Save. Click Deploy > New deployment > type "Web app".
      Execute as: Me.  Who has access: Anyone.  Deploy, allow access when Google asks.
   e. Copy the Web app URL (ends with /exec) into config.php as SHEET_URL.
   f. Optional: in the Products tab, type "Weight (kg)" as the header of the first empty column (N4)
      and fill in each product's packed weight. The tool then works out parcel weight by itself.
   If you change the script later: Deploy > Manage deployments > edit > Version: New version.

8. On your wife's phone: open the site in Chrome > menu > "Add to Home screen".

PHP needs: 8.0+, curl, pdo_sqlite (standard on cPanel).

DAILY USE
- Customer sends details on WhatsApp (send them the template: tap "Copy template",
  save it as a WhatsApp Business quick reply, e.g. /order).
- Copy the customer's message > paste into the green box > details fill in.
- Check the city (pick a district first if unsure) and the customer badge
  (green = good record, yellow/red = has returns).
- Search and add products. Qty and price can be changed (lower price = discount).
  Stock left shows under each product.
- Weight fills from product weights (or type it). Koombiyo charge is estimated from your rate card:
  first kg rate + Rs 100 per extra kg. Change "Charge customer" if you charge less;
  the tool shows how much you cover.
- Create order. It goes to Koombiyo AND your sheet's Orders tab (same Order No numbering).
- End of day: "Select not printed" > Print labels > one PDF with all labels.
- Status updates arrive automatically from Koombiyo and are written to the sheet's Status column
  (Pending > Dispatched > Delivered / Returned). Koombiyo's real charge and weight go into Notes.
- "Export CSV" downloads the month's orders as a backup.

NOTES
- Waybills: the tool uses the pre-allocated waybill numbers in your Koombiyo account.
  If it says "No free waybills", request more from Koombiyo.
- data/rates.json is your rate card (from delivery_rates.csv), used if Koombiyo's API gives no rate.
- Orders are added to the sheet by the tool. Don't type the same order in the sheet by hand.
- If the sheet was unreachable, the order list shows "not in Google Sheet yet" with a Retry button.
- The ✕ button cancels an order in Koombiyo (only before pickup).
- If Koombiyo login fails with "Login location mismatch", ask Koombiyo to allow your server's IP.
- Backup: data/orders.sqlite holds all orders. Download it occasionally.
