=== PawBook ===
Contributors: thecodearena
Tags: booking, pets, appointments, services, scheduler, razorpay, coupons
Requires at least: 5.8
Tested up to: 6.6
Requires PHP: 7.4
Stable tag: 1.5.3
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Run demo appointments and paid pet-service package bookings from WordPress, with scheduling, coupons, Razorpay, emails, customer lookup, and admin reporting.

== Description ==

PawBook is an end-to-end booking and package checkout system for pet-service businesses. It supports two customer journeys:

1. A visitor can request a demo appointment by choosing a service, date, and available time.
2. A customer can purchase a service package through a configurable checkout with coupons, taxes, payment charges, and Razorpay.

The plugin stores customer, address, pet, booking, order, payment, and pricing details in WordPress. Site administrators can manage the complete workflow from the PawBook menu.

= Demo appointment booking =

* Add the responsive booking widget anywhere with `[pawconnect]`.
* Create services with a name, description, price, duration, and active/inactive status.
* Search and select services from the frontend form.
* Configure global or service-specific weekly time slots.
* Set a capacity for each day's slots.
* Block individual dates for holidays or unavailable days.
* Limit how many days ahead customers can book, from 1 to 60 days.
* Automatically hide past times for the current day.
* Prevent bookings in the past, outside the booking window, on blocked dates, or in full slots.
* Collect customer name, phone, optional email, address, city, state, pincode, and coordinates.
* Let customers use browser geolocation to help fill their address.
* Collect pet name, a searchable breed, and customer notes.
* Generate a unique booking reference and show an on-screen confirmation receipt.
* Track booking statuses as pending, confirmed, completed, or cancelled.
* Send booking confirmation, status update, and 24-hour reminder emails.

= Paid packages and checkout =

* Create packages with a plan name, description, MRP, offer price, and active status.
* Display all active packages as responsive checkout cards.
* Preselect a package by ID or slug in a shortcode or checkout URL.
* Collect customer contact and address details, including optional browser geolocation.
* Collect pet name, breed, age, life stage, gender, color, and a 0-10 friendliness score.
* Independently show or hide optional checkout fields from Settings.
* Customize the checkout title, subtitle, and button text.
* Create completed manual orders when Razorpay is disabled or the payable total is zero.
* Redirect successful orders to a selected WordPress confirmation page or fallback URL.
* Display real order details with `[pawconnect_order_confirmation]`.

= Coupons and pricing =

* Create percentage or fixed-amount coupons.
* Set a minimum order amount and a maximum discount.
* Restrict coupons to selected package IDs.
* Limit total uses and uses per customer.
* Restrict a coupon to first-time customers.
* Set an expiry date and active/inactive status.
* Validate coupons in real time and track successful usage.
* Optionally calculate GST on the discounted subtotal.
* Optionally add a percentage or fixed payment-gateway charge.
* Use paise-level rounding and server-calculated totals.
* Store an immutable pricing snapshot on every order.
* Show package price, discount, subtotal, GST, gateway charge, and grand total consistently in checkout, confirmations, emails, admin details, CSV exports, receipts, and invoices.
* Apply no GST or gateway charge when a coupon reduces the subtotal to zero.

= Razorpay payments =

* Enable or disable Razorpay from the WordPress admin.
* Store the Razorpay key ID, key secret, and webhook secret.
* Create Razorpay orders using the server-calculated grand total.
* Verify checkout signatures before completing an order.
* Process signed `payment.captured` and `payment.failed` webhook events.
* Store Razorpay order and payment IDs.
* Track pending, completed, failed, and cancelled payments.
* Let eligible customers retry pending, failed, or cancelled payments.
* Send an optional follow-up email for abandoned Razorpay payments.
* Show the most recent webhook event in Settings.

= Customer experience =

* Use `[pawconnect_customer_portal]` to let a customer look up an order with its reference and email address.
* Show order and payment status, pricing details, and payment-retry controls where eligible.
* Use `[pawconnect_order_confirmation]` for a designed post-checkout confirmation page.
* Configure links back to the packages page and customer portal.
* Customize global colors, thank-you page colors, font family, and custom CSS.
* Use a configurable logo, business name, phone, email addresses, and currency symbol.

= Administration and reporting =

* Dashboard summaries for demo bookings, paid and unpaid orders, and revenue.
* Recent demo bookings and upcoming appointment views.
* Separate management screens for demo bookings and paid bookings.
* Search bookings and orders by customer, contact, pet, location, or reference data.
* Filter by status and date range.
* Update statuses, resend emails, or delete records.
* Export filtered demo bookings and paid orders to CSV.
* Open WhatsApp conversations from customer phone numbers.
* Open saved coordinates in Google Maps.
* View an optional order timeline.
* Print an order receipt/invoice.
* Track refund status, refund ID, amount, and internal notes.
* Create, edit, activate, deactivate, and delete services, packages, breeds, and coupons.
* Manage a local searchable pet-breed list with seeded defaults.

= Email notifications =

* Branded HTML emails with the configured logo, business details, colors, and sender address.
* Separate switches for demo customer, demo admin, status update, paid customer, paid admin, pending-payment, and failed-payment emails.
* Configurable subjects and message bodies using booking and customer placeholders.
* Paid-order templates include order, pricing, coupon, and Razorpay data.
* Send admin copies to one or more configured email addresses.
* Preview supported email types from Settings.
* Manually resend customer emails from booking and order screens.

= REST API and integrations =

PawBook includes public endpoints for frontend booking and checkout, plus API-key-protected admin endpoints. The base namespace is:

`/wp-json/pawconnect/v1`

Public read endpoints:

* `GET /services`
* `GET /breeds`
* `GET /slots?service_id={id}`
* `GET /packages`
* `GET /packages?package={id-or-slug}`
* `GET /packages/{id-or-slug}`

Public workflow endpoints:

* `POST /book`
* `POST /checkout/validate-coupon`
* `POST /checkout/create-order`
* `POST /checkout/verify-payment`
* `POST /checkout/payment-status`
* `POST /checkout/order-lookup`
* `POST /checkout/retry-payment`
* `POST /razorpay/webhook`

API-key-protected admin endpoints:

* `GET|POST /admin/bookings`
* `PATCH /admin/bookings/{id}/status`
* `GET /admin/orders`
* `GET|POST /admin/coupons`
* `GET /admin/coupons/{id}`
* `GET /admin/slots`

Send the generated API key in `X-PawBook-Key` or as a Bearer token. See `PAWCONNECT_API_GUIDE.md` in the plugin folder for request parameters and response examples.

= Security and data integrity =

* WordPress capability checks and nonces protect admin actions.
* API-key authentication protects admin REST resources.
* Inputs are sanitized and database queries use the WordPress database API.
* Demo booking submissions are rate-limited by IP address.
* Slot availability and all checkout pricing are recalculated on the server.
* Razorpay payments and webhooks use HMAC signature verification.
* Unique references identify bookings and paid orders.
* Historical pricing snapshots prevent later settings changes from altering old order totals.

== Shortcodes ==

= Demo booking =

`[pawconnect]`

Displays the service, date, slot, customer, address, and pet booking form.

= Package checkout =

`[pawconnect_checkout]`

Displays all active packages and the checkout form.

Preselect a package by database ID:

`[pawconnect_checkout package="1"]`

Preselect a package by generated slug:

`[pawconnect_checkout package="early-learning-program"]`

You can also preselect a package with a checkout URL:

`/checkout/?package=early-learning-program`

= Order confirmation =

`[pawconnect_order_confirmation]`

Place this on the page selected under PawBook > Settings > Order confirmation page.

= Customer order portal =

`[pawconnect_customer_portal]`

Lets customers securely look up their order using the order reference and matching email address, and retry eligible payments.

== Installation ==

1. Upload the `pawconnect` folder to `/wp-content/plugins/`, or install its ZIP from Plugins > Add New > Upload Plugin.
2. Activate PawBook from the Plugins screen.
3. Open PawBook > Settings and configure business details, email, branding, currency, checkout, and optional Razorpay credentials.
4. Create services under PawBook > Services.
5. Configure weekly schedules, capacity, and blocked dates under PawBook > Time slots.
6. Add `[pawconnect]` to a page for demo appointment requests.
7. To sell packages, create packages under PawBook > Packages and add `[pawconnect_checkout]` to a checkout page.
8. Create a confirmation page containing `[pawconnect_order_confirmation]`, then select it in Settings.
9. Optionally create a customer portal page containing `[pawconnect_customer_portal]`.
10. If Razorpay is enabled, add the displayed webhook URL to the Razorpay dashboard and use the same webhook secret in both systems.

Database tables and default records are created automatically on activation. Existing installations are upgraded automatically when the plugin version changes.

== Configuration ==

= Business and booking settings =

Configure the business name, notification email list, sender email, phone, logo, currency, booking window, success message, and whether admins receive copies.

= Appearance =

Configure brand, navy, accent, checkout background, checkout panel, thank-you page, text, success, and button colors. You can also set a font-family value and add custom CSS.

= Checkout and feature switches =

Configure package and portal URLs, the confirmation page, checkout copy, optional form fields, payment recovery, customer portal, order timeline, receipts, refund tracking, abandoned-payment follow-up, WhatsApp links, and webhook status.

= GST and gateway charges =

Both are optional. GST accepts a percentage. Gateway charges may be a percentage of the discounted subtotal or a fixed currency amount. Gateway charges are only applied when an active payment gateway is available.

= Email =

Enable only the messages you need. Configure subjects and bodies with the placeholders shown in Settings, then use the built-in previews to confirm the result.

== Frequently Asked Questions ==

= Can PawBook be used without Razorpay? =

Yes. Demo bookings do not require a payment gateway. Paid-package checkout also works without Razorpay and records the order as a completed manual order.

= Can I link a Buy Now button to one package? =

Yes. Link the button to the checkout page with `?package=ID` or `?package=package-slug`. The same values work in the checkout shortcode's `package` attribute.

= Why is a time slot unavailable? =

The slot may be in the past, at capacity, outside the configured booking window, on a blocked date, or unavailable for the selected service.

= When are coupon uses counted? =

Coupon usage is incremented when the related order becomes completed, including a verified Razorpay payment or a zero/manual checkout.

= How do customers retry a payment? =

Enable Payment recovery links and publish the customer portal shortcode. A customer can look up a pending, failed, or cancelled order with its reference and email, then retry payment.

= Are old order totals changed when tax settings change? =

No. Each order stores its package price, discount, subtotal, GST, gateway charge, and final total as a pricing snapshot.

= How are reminders and payment follow-ups sent? =

WordPress schedules hourly checks. Confirmed appointments due within 24 hours receive one reminder. Eligible pending Razorpay orders can receive one follow-up after 30 minutes when the relevant feature and email switch are enabled. WordPress cron depends on site traffic unless a server cron is configured.

= Why are emails not arriving? =

Confirm the sender and recipient settings, check spam, and verify that WordPress can send mail. On production sites, an authenticated SMTP or transactional email plugin is recommended.

= Where is the API key? =

It appears under PawBook > Settings. You can regenerate it there. Regenerating the key immediately invalidates the old key.

= Does uninstall remove plugin data? =

The uninstall routine removes the demo booking, service, time-slot, and breed tables plus the main settings option. Review and back up your database before uninstalling if you need to retain data.

== External Services and Privacy ==

PawBook can communicate with the following third-party services when the related feature is used:

* Razorpay: checkout loads Razorpay's hosted JavaScript and the server sends order/payment requests to Razorpay. Customer, order, and payment data may be processed according to Razorpay's terms and privacy policy.
* OpenStreetMap Nominatim: when a customer clicks "Use my location," browser coordinates are sent to Nominatim for reverse geocoding.
* Google Maps: administrators may open a saved coordinate in Google Maps.
* WhatsApp: administrators may open a chat link containing the customer's phone number.

Browser geolocation requires the visitor's permission. Site owners are responsible for providing an appropriate privacy notice, obtaining any required consent, configuring data retention, and complying with applicable laws and third-party terms.

== Additional Documentation ==

The plugin folder includes:

* `DEMO_BOOKING_GUIDE.md` - demo booking setup and workflow.
* `SESSION_BUYING_GUIDE.md` - package, coupon, checkout, and payment setup.
* `PAWCONNECT_API_GUIDE.md` - admin and public REST API examples.
* `BREED_SYSTEM_GUIDE.md` - local pet-breed management.
* `TROUBLESHOOTING.md` - common booking-form diagnostics.
* `UPGRADE_GUIDE_v1.1.0.md` - upgrade notes for older installations.

== Changelog ==

= 1.5.3 =

* Matched the paid order confirmation page to the supplied SourcePackages reference design, including the sticky payment summary, numbered next steps, package card, pet/parent details, responsive layout, and accessible copy-reference action.

= 1.5.2 =

* Fixed the demo booking form staying visible behind the success screen after booking — an unconditional `display: grid` rule was overriding the browser's own hide behavior, so the `hidden` attribute wasn't actually hiding it.
* Redesigned the booking confirmation receipt with a header strip and a styled reference code for a more polished look.
* Fixed booking-detail rows in confirmation/status emails wrapping awkwardly on mobile — switched from flexbox to table-based rows, which mobile mail clients render far more reliably.

= 1.5.1 =

* Persisted the demo booking confirmation to the browser's localStorage, so reopening or reloading the page after a successful booking keeps showing the "Demo Request Received" screen instead of resetting to the empty form. Clears automatically when "Book Another Demo" is clicked.

= 1.5.0 =

* Animated the demo booking success screen: a drawn-in checkmark, pulsing ring, confetti burst, and staggered reveal of each booking detail row, plus a renamed "Book Another Demo" button.

= 1.4.3 =

* Fixed a mobile layout bug on the demo booking form where the horizontally-scrolling date picker forced the entire two-column layout to overflow the viewport instead of collapsing to a single column.

= 1.4.2 =

* Redesigned the transactional email template (demo confirmations, status updates, reminders, and paid-order emails) with a branded header banner, accent bar, and an auto-generated "Booking Details" card, plus a hidden preheader for better inbox previews.

= 1.4.1 =

* Reworked the demo booking form layout into a two-column editorial design with a sticky sidebar, numbered sections, pill-style service/date/time chips, and a live selection summary.

= 1.4.0 =

* Redesigned the demo booking form (`[pawconnect]`) with a new gradient header, icon-labeled sections, pill-style date/time chips, icon-prefixed inputs, and a boarding-pass style success receipt.

= 1.3.0 =

* Added configurable GST and gateway-independent percentage/fixed payment charges.
* Added persisted pricing snapshots for accurate historical orders and invoices.
* Added package price, discount, subtotal, GST, payment-gateway charge, and grand total across checkout, order details, emails, CSV exports, and printable invoices.
* Ensured Razorpay and payment retries use the server-calculated grand total.
* Added nonnegative validation, paise-level rounding, legacy-order migration, and pricing regression tests.

= 1.2.1 =

* Added configurable order confirmation page selection.
* Added `[pawconnect_order_confirmation]` for real order confirmation details.
* Redirected successful checkout to the selected confirmation page with the order reference.
* Fixed coupon totals so discounts update the displayed total and payable amount.

= 1.1.3 =

* Added past-time filtering for same-day demo booking slots.
* Added service-specific slots, slot capacity, and blocked dates.
* Added Razorpay webhook handling and payment recovery.
* Added CSV exports, date filters, WhatsApp links, booking reminders, customer order lookup, invoices, refunds, and order timelines.

= 1.1.2 =

* Added geolocation-assisted address capture for demo bookings and paid checkout orders.

= 1.1.1 =

* Fixed breed lists stopping at Gordon Setter by loading all breeds and backfilling missing default breeds on upgrade.

= 1.1.0 =

* Added local pet-breed management and booking-form breed selection.
* Added packages, coupons, paid orders, checkout, and Razorpay integration.

= 1.0.0 =

* Initial release.
