=== Avo – AI Shopping Assistant for WooCommerce ===
Contributors: corpela
Donate link: https://corpela.com
Tags: woocommerce, ai search, product search, smart search, ai
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 7.4
Requires Plugins: woocommerce
WC requires at least: 5.0
WC tested up to: 9.3
Stable tag: 1.3.3
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

AI shopping assistant and smart product search for WooCommerce. Understands buyer intent, recommends in-stock products, and boosts store sales.

== Description ==

**Avo** transforms your WooCommerce store into an intelligent shopping destination. It places a sleek floating search pill at the bottom of your storefront (e.g., *"What are you shopping for today? →"*).

When a shopper asks a natural question like *"I need a Casio watch for my wife"*, Avo connects to OpenRouter AI to extract buyer intent (brand, gender target, categories, price budget), queries your local WooCommerce catalog, and displays instant matching product cards inside a modern popup modal—complete with one-click collection redirects!

### Key Features

* **Floating Search Pill**: Pinned at the bottom-center of your storefront with a modern frosted glass aesthetic.
* **Natural Language Intent Parsing**: Powered by OpenRouter AI (`google/gemini-2.0-flash-001`, `openai/gpt-4o-mini`, `anthropic/claude-3.5-haiku`).
* **Direct WooCommerce DB Querying**: Queries real-time inventory and pricing directly from your store database.
* **Instant Category Link Banner**: One-click *"Explore Collection: View all Women's Casio Watches →"* button.
* **AJAX Add to Cart**: Allows shoppers to add items directly to their cart from the results modal without page reloads.
* **Merchant Analytics & Demand Insights**: Track top searched queries, uncover zero-result demand gaps, and attribute sales conversions.
* **Customizable Admin Settings**: Change AI model, placeholder text, accent color, and test API connectivity with one click.
* **Rate-Limiting Protection**: Server-side nonce check and IP rate-limiting to prevent unauthorized use of your OpenRouter API credits.

== Third-Party Services ==

This plugin relies on the **OpenRouter API** to perform natural language intent recognition and generate conversational shopping recommendations.

* **Service Provider**: OpenRouter, LLC (https://openrouter.ai)
* **Terms of Service**: https://openrouter.ai/terms
* **Privacy Policy**: https://openrouter.ai/privacy
* **What Data is Transmitted**: When a customer performs a search via the assistant widget, their search text query and the store's public taxonomy names (category and attribute names) are sent to OpenRouter via a secure HTTPS server-to-server request. No customer personal identifiable information (PII) or customer account credentials are ever transmitted.

== Installation ==

1. Upload the plugin folder to the `/wp-content/plugins/` directory, or install directly through **Plugins > Add New > Upload Plugin**.
2. Activate the plugin through the **Plugins** menu in WordPress.
3. Ensure WooCommerce is installed and active with published products in your catalog.
4. Navigate to **Avo Assistant** in your WordPress admin menu (or click the **Settings** shortcut on the Plugins screen).
5. Enter your **OpenRouter API Key** (obtainable from https://openrouter.ai/keys). You can choose any model including the free `openrouter/free` tier.
6. Click **Test Connection** to confirm connectivity.
7. Customize optional storefront display settings (placeholder text, accent color, max recommended products) and click **Save All Changes**. The search pill will immediately appear on your storefront.

== Frequently Asked Questions ==

= Do I need an OpenRouter account? =
Yes. Store owners must have an active OpenRouter account and API key. You can use the free `openrouter/free` model tier or low-cost models. Get your key at https://openrouter.ai.

= Which AI model is recommended? =
You can use `openrouter/free` to run completely free without consuming API credits, or `google/gemini-2.0-flash-001` / `openai/gpt-4o-mini` for near-instant (1-2s) response times and minimal cost.

= Is my API key exposed to visitors? =
No. The OpenRouter API key is stored securely in WordPress database settings and all API calls are made server-side through the WordPress REST API with nonces.

= Can I place the search widget manually with a shortcode? =
Yes! You can place the search bar anywhere using the shortcode `[avoaisha_search]` in your pages, header, footer, or block templates.

== Screenshots ==

1. Floating search pill on storefront.
2. AI results modal showing product recommendations and collection banner.
3. Plugin admin settings panel with Test Connection button.

== Changelog ==

= 1.3.3 =
* New: Added full-screen Onboarding Setup Wizard (`admin.php?page=avoaisha-onboarding`) matching Avo's signature minimalist widget aesthetic.
* New: Interactive 5-step guided journey featuring store niche calibration, real-time OpenRouter AI connection testing, and live storefront floating pill preview.
* Improved: Refined administrative asset routing and core activation redirect parameters to achieve 100% clean WordPress Plugin Check compliance.

= 1.3.2 =
* Improved: Enhanced database query cache handling and PHPCS annotations in Analytics to resolve direct database query NoCaching warnings.
* Improved: Added forward compatibility for WordPress 7.0 native WordPress AI Client (`wp_ai_client_prompt()`) and refined external AI provider endpoint references to resolve Plugin Check warnings.

= 1.3.1 =
* Fixed: Critical search continuity bug resolved. Implemented zero-failure catalog keyword fallback when OpenRouter API key is unconfigured, credit quota is exhausted, or temporary network interruptions occur.
* Improved: Standardized database queries in Analytics engine with persistent caching (`wp_cache_*`) and strict WordPress table prefix compliance, resolving Plugin Check warnings.

= 1.3.0 =
* New: Added Merchant Analytics & Insights Dashboard (Tab 5 in Settings) featuring real-time KPI metric cards (Total AI Searches, Conversions, Conversion Rate %, and Missed Demand).
* New: Added Missed Sales Opportunities table showing zero-result searches to help store owners identify what customers want to buy that isn't currently stocked.
* New: Added Top Searched Terms table tracking popular customer queries and direct Add-to-Cart conversions.
* New: Added date range filtering (Last 7 Days, Last 30 Days, Last 90 Days, All Time) with one-click reset logs action.
* Improved: Refined administrative dashboard layout with responsive 2-column grid and optimized spacing across all setting sections.
* Improved: GDPR-compliant lightweight analytics storage using custom indexed SQL table with zero customer PII and automated daily log pruning.
* Fixed: Corrected container spacing, button alignment, and toggle switch margins in the settings panel.

= 1.2.0 =
* Feature: Redesigned admin settings with a modern tabbed navigation interface (API & Model, Widget Design, Mobile Rules, Store Behavior).
* Feature: Added one-click sample prompt preset templates for instant setup across different store niches.
* Feature: Added one-click copy shortcode action in the settings screen.
* Enhancement: Added persistent active tab memory so settings saves retain your active tab.

= 1.1.1 =
* Feature: Added admin setting to hide the floating search assistant on single product pages.
* Performance: Conditionally skip loading frontend styles and scripts on product pages when hidden.

= 1.1.0 =
* Feature: Smart auto-detection of theme mobile footer navigation bars (Storefront, WoodMart, Flatsome, Astra, Botiga, sticky add-to-cart bars) with dynamic automatic elevation so footer menus are never hidden.
* Feature: Added automatic page-level exclusion toggle to hide floating search widget on Cart and Checkout pages to avoid obstructing checkout buttons.
* Feature: Added customizable mobile bottom offset setting in plugin admin settings.
* Enhancement: Added iOS safe-area-inset support for iPhone bottom gesture bars.

= 1.0.0 =
* Initial release on WordPress.org directory.
* Floating search pill widget with frosted glass design.
* OpenRouter API intent extraction engine.
* Real-time WooCommerce product querying and category matching.
* Instant AJAX Add to Cart support in modal.
