=== Khuza Listing Intelligence ===
Contributors: khuzaplugins
Tags: real estate, chatbot, lead generation, valuation, property
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.3.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

AI-powered listing chat widget for property sites — answers buyer questions, gives live valuations, books viewings, and scores leads.

== Description ==

**Turn every property listing into a conversation.**

Khuza Listing Intelligence adds an AI chat widget ("Hani") to your property listing pages. Visitors can ask questions about a listing in plain language and get instant, context-aware answers — plus a live price valuation, a viewing booking, and a WhatsApp fallback — without leaving your page.

Every conversation becomes a scored lead routed straight to your Rehani Soko dashboard.

Connect your site once from **Settings → Listing Intelligence**, then drop the `[khuza_bot]` shortcode on a listing page (or let the plugin auto-place it near your theme's contact form).

= What visitors can do =

* **Ask about a listing** — Hani answers using the listing's own details (price, location, beds, baths, type).
* **Get a live valuation** — an inline Under / Fair / Over gauge from the RehAnalytics model (requires a connected account with a RehAnalytics licence; otherwise Hani answers in prose).
* **Book a viewing** — checks agent availability and submits an appointment request.
* **Reach you on WhatsApp** — an optional fallback CTA inside the widget.

= Why agents install it =

* **Capture more leads** — every chat is a scored lead in your existing Rehani inbox.
* **Answer 24/7** — buyers get instant answers even when you're offline.
* **Works with your theme** — auto-detects listing details on RealHomes, Houzez, WP Residence, and Khuza; or set them manually via shortcode.
* **Secure by design** — the API key is stored server-side and never exposed to the browser; all backend calls run through a nonce-protected PHP proxy.

= How it works =

1. Install the plugin and connect your site with a one-time token from your Rehani dashboard.
2. Place `[khuza_bot]` on a listing page (or use auto-placement).
3. The widget reads the listing context and talks to the Rehani backend through the plugin's server-side proxy.
4. Leads, bookings, and valuations flow to your Rehani Soko dashboard.

**Requirements:**

* A Rehani Soko account (register at rehanisoko.com)
* A real estate theme with single property listing pages
* WordPress 6.0 or higher

== External Services ==

This plugin relies on third-party services operated by Rehani Soko. All backend
requests are made server-side through the plugin's PHP proxy — the browser never
contacts these services directly.

= Rehani Soko API =

* Service: https://render-prod.rehanisoko-internal.com/api/v1
* Used for: connecting your WordPress site, answering chat questions, creating leads, booking viewings, checking agent availability, and requesting a listing valuation.
* Data sent on connect: your site URL, connection token, plugin version, WordPress version, timezone, and admin email.
* Data sent during use: the visitor's chat messages, the listing context (title, price, location, beds, baths, type), and any contact details a visitor voluntarily provides when creating a lead or booking a viewing (such as name, email, and phone number).
* When: on plugin connect, and when a visitor interacts with the chat widget on a listing page.
* Terms of service: https://www.rehanisoko.com/terms-of-service
* Privacy policy: https://www.rehanisoko.com/privacy-policy

= Rehani Soko website =

* Service: https://www.rehanisoko.com
* Used for: generating your connection token and viewing leads/bookings in your dashboard.
* Data sent: none beyond what you enter when logged into your own dashboard.
* Terms of service: https://www.rehanisoko.com/terms-of-service
* Privacy policy: https://www.rehanisoko.com/privacy-policy

== Installation ==

1. Upload the plugin through Plugins > Add New > Upload, or install from the directory.
2. Activate it.
3. Go to **Settings > Listing Intelligence** and paste your one-time connect token from your Rehani dashboard, then Save.
4. Add `[khuza_bot]` to a listing page, or choose an auto-placement option in the settings.

To get a token: log in at rehanisoko.com → Agent Dashboard → generate a connection token.

== Frequently Asked Questions ==

= Does it cost anything to install? =

No. Installation and setup are free. A Rehani Soko account is required to connect.

= Do I need a Rehani Soko account? =

Yes. Sign up at rehanisoko.com and generate a one-time connect token from your dashboard.

= Where does the widget appear? =

On single property listing pages, via the `[khuza_bot]` shortcode or an auto-placement option. The shortcode is the most reliable method and works on any theme.

= Which themes does it work with? =

Listing details are auto-detected on RealHomes, Houzez, WP Residence, and Khuza. On other themes, pass the details manually, e.g. `[khuza_bot listing_title="3-bed Kilimani" listing_price="KES 12M"]`.

= Is my API key exposed to visitors? =

No. The key is stored server-side in WordPress options and attached by the PHP proxy. It is never sent to the browser or visible in JavaScript.

= Does the widget work without a valuation licence? =

Yes. If no RehAnalytics licence is present, Hani still answers questions, books viewings, and captures leads — it simply skips the live valuation gauge.

== Screenshots ==

1. The Hani chat widget on a single property listing, answering a buyer's question.
2. The inline price valuation gauge (Under / Fair / Over).
3. Booking a viewing from the agent's available time slots.
4. The agent's "My Availability" editor — days, time slots, and timezone.
5. The plugin settings and connect screen.

== Changelog ==

= 1.3.1 =
* Security: the REST proxy now requires an authenticated user with a capability for actions that read or write an agent's private data (availability, bookings, open houses). Guest actions (chat, lead, valuation, public lookups) remain nonce-protected and public.

= 1.3.0 =
* Renamed the plugin to "Khuza Listing Intelligence". Your settings and connection carry over automatically.
* All styles and scripts now load through the WordPress enqueue system.
* Internal function, option, and handle prefixes lengthened to avoid collisions with other plugins.

= 1.2.2 =
* Hardened output escaping across admin settings, the shortcode, and placement for WordPress.org compliance.

= 1.2.1 =
* Lead capture: a visitor's name, email, and phone are now saved with the lead, and each lead records which listing it came from (title + property URL).

= 1.2.0 =
* Booking and confirmation emails now send through the platform's email service, so agents and guests reliably receive them.

= 1.1.0 =
* Agent availability: set your viewing hours — days, time slots, and timezone — from the WordPress dashboard under "My Availability".
* Viewing bookings: visitors pick from your available slots and you receive an email for each new request; a slot you're already booked for is removed across all your listings.
* Confirm / decline: review viewing requests under "My Bookings" and the guest is emailed your decision.
* Viewing types: Private Viewing and General Consultation.

= 1.0.0 =
* Initial release: AI listing chat widget with live valuation, viewing bookings, lead scoring, and WhatsApp fallback, connected via a secure server-side proxy.

== Upgrade Notice ==

= 1.2.1 =
Leads now capture visitor contact details and the originating listing. Adds agent availability and viewing bookings with confirm/decline.

= 1.0.0 =
Initial release.
