=== Mersal Assistant ===
Contributors: mersal
Tags: ai, chatbot, assistant, woocommerce, search, support, knowledge base
Requires at least: 6.0
Tested up to: 6.8
Requires PHP: 7.4
Stable tag: 1.9.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A live AI assistant and smart product search for WordPress & WooCommerce: knowledge base, RAG answering, in-chat actions, and 10 integrations.

== Description ==

Mersal Assistant turns your site content and WooCommerce catalog into a knowledgeable AI assistant. It answers visitor questions from your own content (Retrieval-Augmented Generation), powers a semantic product search, performs real actions during chats (order lookup, lead capture, coupons, and more), and connects to your favourite tools.

**Highlights**

* Pixel-faithful admin dashboard (Overview, Conversations, Knowledge Base, Actions, Integrations, Team & Roles, Settings).
* Configurable OpenAI-compatible LLM provider (OpenAI, Azure OpenAI, OpenRouter, Groq, local servers).
* Self-contained vector knowledge base stored in your own database (MySQL + PHP cosine similarity) — no external vector DB required.
* Front-end chat widget + `[mersal_search]` smart-search shortcode.
* Nine assistant actions exposed to the model as tools.
* Ten integrations: WooCommerce, WhatsApp, Messenger, Slack, Zapier, Google Calendar, HubSpot, Mailchimp, Stripe, Intercom.
* Privacy-first: PII masking, GDPR consent, configurable retention, allowed-domains, profanity filter.

== Installation ==

1. Upload the `mersal-assistant` folder to `/wp-content/plugins/`, or install the ZIP via Plugins → Add New → Upload.
2. Activate **Mersal Assistant** through the Plugins menu.
3. Open **Mersal** in the admin sidebar.
4. Go to **Settings → AI & Model** and enter your OpenAI-compatible API base URL and API key.
5. Go to **Knowledge Base → Add source** and index your site content (WordPress content, sitemap, crawl, files, or WooCommerce products).
6. (Optional) Connect integrations under **Integrations**, and place `[mersal_search]` on any page.

= Loading as an unpacked plugin =

No build step is required. The admin UI and front-end widget are hand-written vanilla JavaScript (CSP-safe), so the plugin runs as-is once copied into `/wp-content/plugins/`.

== Configuration prerequisites for integrations ==

Some providers require you to create an app and supply credentials in the Connect dialog:

* **WhatsApp / Messenger:** a Meta app with the Cloud API / Pages webhook. Use the webhook URLs shown in the Connect dialog and your chosen verify token.
* **Google Calendar:** an OAuth client (Client ID/Secret). Add the shown redirect URI to your Google Cloud console.
* **Slack / HubSpot / Intercom / Mailchimp / Stripe:** a bot token / private-app token / API key.
* **Zapier:** a "Catch Hook" URL.
* **WooCommerce:** no credentials — connects natively when WooCommerce is active.

== Frequently Asked Questions ==

= Does it work without WooCommerce? =
Yes. WooCommerce is optional; product/order/stock actions activate automatically when WooCommerce is present.

= Where is my data stored? =
All conversations, leads, and knowledge embeddings are stored in your own WordPress database. Credentials are encrypted at rest. Only the messages you send to your configured LLM provider leave your server.

= Is it accessible / CSP-safe? =
The UI uses no inline scripts and no `eval`. All dynamic content is rendered via DOM text nodes, preventing XSS.

== Manual test checklist ==

Activation & teardown
* Activate the plugin: tables `wp_mersal_*` are created; no PHP notices with `WP_DEBUG` on.
* Deactivate: scheduled events are cleared; data is preserved.
* Uninstall (delete): tables, options, transients and capabilities are removed.

Admin dashboard
* Each sidebar item renders its screen; the active item is highlighted.
* Toggle any switch / segmented control — a "Saved" toast appears and the value persists after reload.
* Overview shows real counts (zeros on a fresh install) with correct empty states.
* Add a knowledge source; it appears in the table and indexing is queued.
* Re-sync and delete a source work.
* Open the Action config drawer; coupon shows extra rules; Save closes it.
* Open the Connect dialog for an integration; submitting credentials connects or shows a clear error.
* Settings → AI & Model: saving the API key shows "(saved)" on reload and never returns the key.

Front-end
* The launcher appears in the configured position; opening it shows the welcome message.
* With GDPR enabled, the consent gate appears before chatting.
* Sending a message returns an answer (or the fallback if the provider is unconfigured); sources and follow-ups render.
* `[mersal_search]` renders the styled field; typing returns product cards (with WooCommerce active).

Security
* Calling `/wp-json/mersal/v1/chat` without a valid nonce returns 403.
* Rapid repeated requests return 429 (rate limited).
* Restricting allowed domains blocks requests from other origins.

== Changelog ==

= 1.9.2 =
* Fixed the assistant occasionally posting its own internal notes into the chat ("We need to respond…", "According to the knowledge base…", "Thus we need to call…"). Every reply now passes through a guard that removes leaked reasoning, hidden thinking blocks and stray tool syntax before the customer sees it; if a reply is nothing but reasoning, the assistant is asked again for the customer-facing message instead of posting it.
* Replies are stricter and more professional by default: lead with the answer, no filler openings, no invented prices or delivery times, no Markdown symbols left showing in the chat bubble.
* Arabic dashboard: translated the rest of the interface — the Playbook & Payments settings, the Orders & Requests screen, receipt review, notifications and the integration fields that were still appearing in English.

= 1.8.2 =
* Fixed WooCommerce product indexing timing out on large catalogues. Product fields are now read directly from the database instead of loading a full WC_Product per row, which on stores running inventory/pricing add-ons (e.g. Atum Multi-Inventory) added seconds of queries per product and blew the 300s sync cap — thousands of products never got indexed. A full catalogue now indexes in seconds.
* Fixed knowledge coverage showing a misleadingly low percentage when the AI provider offers no embeddings endpoint. Keyword-only indexing is fully searchable and now reports its true coverage instead of 0% for the (never-created) vectors.
* Fixed the admin assistant launcher (button + greeting bubble) still showing on the plugin's own screen after "Show the admin assistant" was switched off.
* Full-width admin layout fix and hidden Screen Options/Help tabs on the plugin screen so nothing floats over the app chrome.

= 1.8.0 =
* Fixed plugin updates never being offered. The updater was checking an address that does not exist, so no site ever saw an update notice no matter how many releases were published. It now reads the same release channel as the rest of the Mersal suite.
* Added Settings → Updates: your installed version, the latest available version, the release notes for it, and a "Check for updates" button.
* Added an "Install updates automatically" switch. Off by default — turn it on and new versions install themselves in the background.

= 1.7.1 =
* Fixed the knowledge base indexing only the 500 newest products (and 500 posts/pages). Larger catalogues were silently cut off, so anything older simply could not be found in search or answered about in chat. All products are now indexed, streamed in pages so memory stays flat on big stores.
* **After updating, re-sync your sources** (Knowledge → Sync now) so the products that were previously skipped get indexed. Sources also re-sync automatically every 24 hours.
* Re-indexing no longer clears the index before rebuilding it: a sync interrupted part way (a large catalogue hitting the server time limit) now leaves the previous index intact instead of a half-empty one.
* Search now says "no exact match for what you searched" and labels the results as suggestions when nothing in the shop matches your full query, instead of silently showing loosely-related products.

= 1.7.0 =
* Smart search now matches every Arabic spelling in both directions — searching "اسنان" finds "أسنان" and vice-versa. Previously only the query side was normalised, so the second word of a multi-word search silently matched nothing and results looked like they used the first word only.
* Search results are now ranked by how many of your words a product matches, and results matching far fewer words are dropped — searching for a toothbrush no longer returns every other kind of brush.
* Added control over where the chat icon appears: all pages, home only, inner pages only, or nowhere, with per-page-type exceptions (cart, checkout, my account, products, archives, 404…), hiding by specific page ID, and separate hide-on-mobile / hide-on-desktop switches.
* Added pixel control over the chat icon's position — side and bottom spacing, set separately for desktop and mobile — plus the launcher size.
* Added switches for the icons inside the chat window: the "talk to a human" button, reply rating, and the in-chat search bar.
* Added control over the admin copilot icon: show or hide it, choose its side, and set its spacing.

= 1.2.0 =
* Redesigned the Mersal Account screen: account status and AI Pool status are now shown as simple connected/active pills — no AI Pool key name, masked key, or endpoint is exposed in the dashboard or REST payload.
* Fixed a bug where a successful "Sync now" could still show a false "connected"/"synced" success toast even when AI Pool provisioning failed behind it; the real error now always surfaces.
* Added a clearer message when a REST session nonce expires on a long-open tab, instead of a raw WordPress error string.
* Added self-hosted plugin updates sourced from mersal.it (this plugin isn't distributed on WordPress.org), wired into the standard Plugins screen "update available" / "view details" UI.
* Added a Mersal Assistant item to the wp-admin toolbar with a badge for conversations waiting on a human agent, and a dropdown of recent conversation activity.
* Replaced the generic dashicon with the Mersal logo across the wp-admin menu, the dashboard sidebar, and the new toolbar item; menu label now reads "Mersal Assistant".
* Fixed the dashboard's notification bell, which previously showed a permanent, non-functional "unread" dot; it's now wired to escalated conversations and clicking it opens them.
* Fixed a namespace bug that would have made the new toolbar registration fatal-error under PHP's qualified-name import resolution.

= 1.0.0 =
* Initial release: admin dashboard, knowledge base + vector search, RAG chat engine, front-end widget, smart-search shortcode, 9 actions, 10 integrations, notifications, retention.

== Upgrade Notice ==

= 1.8.0 =
Fixes update notices never appearing, and adds an Updates screen with release notes plus an optional automatic-update switch.

= 1.7.1 =
Important: fixes catalogues larger than 500 products being only partially indexed. Re-sync your sources after updating.

= 1.7.0 =
Fixes Arabic multi-word product search (spelling variants now match both ways, results ranked by word coverage) and adds full control over where the chat and admin assistant icons appear.

= 1.2.0 =
Redesigned Mersal Account screen (AI Pool details hidden), fixed a misleading sync success message, added mersal.it-sourced plugin updates and a wp-admin toolbar notification shortcut.

= 1.0.0 =
First public release.
