=== Koply Search for WooCommerce ===
Contributors: koply
Tags: search, product search, woocommerce search, ajax search, ai search
Requires at least: 6.3
Tested up to: 7.1
Requires PHP: 7.4
WC requires at least: 8.0
WC tested up to: 11.3
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Product search for WooCommerce that tolerates typos, learns your catalog's synonyms and rescues zero-result searches. Hosted in the EU.

== Description ==

The default WordPress search compares what shoppers type with the text of your titles and descriptions. A product catalog needs more: shoppers misspell, use other words for the same thing, and leave when they see "0 results".

Koply replaces it with an instant search that shows products as shoppers type:

* **Typo tolerance** on every plan.
* **Synonyms you approve**: Koply analyses your catalog and suggests synonym groups; you decide which ones apply.
* **Zero-results recovery with AI**: when a search finds nothing, Koply rephrases it with the context of your catalog and shows alternatives.
* **Add to cart from the results**, using the native WooCommerce cart. Mini-cart and cart block refresh on their own.
* **See what your search sells**: orders are reported from the order received page, so the Koply dashboard shows revenue and orders that come after a search.
* **Unlimited searches** and a fixed monthly price. Permanent free plan up to 100 products.
* **Hosted in the EU** (Sweden). No cookies.

= What the plugin does =

1. **Generates your product feed** (Google Shopping XML format) in the background and keeps it up to date every hour when your catalog changes. Only products visible in your shop or search are included, with price, sale price, image, categories, brand and stock.
2. **Adds the Koply widget** to your store search box. Colors, language and texts are managed from the Koply panel, with no changes in WordPress.
3. **Adds to cart** from the search results with the native WooCommerce AJAX endpoint. Variable and grouped products open their product page so the shopper can choose.
4. **Reports orders** (enabled by default) so you can measure revenue from search. No customer data is sent.

Compatible with HPOS (High-Performance Order Storage) and with the cart and checkout blocks.

= Setup =

1. Install and activate the plugin. Go to **WooCommerce → Koply Search** and copy your feed address.
2. Create a free account at koply.eu and add a site with your domain and that feed address.
3. Copy the API key from **Sites → Embed code** and paste it in the plugin settings.

== External services ==

This plugin connects to Koply (koply.eu), a site search service operated from the European Union. It is required: the search, the results and the statistics are provided by Koply.

**1. Search widget, loaded in the visitor's browser**

On every page of your store, once an API key is saved and the widget is enabled, the visitor's browser loads the widget script from `https://koply.eu/widget/koply.js` and calls the Koply API at `https://api.koply.eu`:

* To search: the text typed in the search box, your site's API key and a random session identifier.
* To measure (unless you choose to wait for consent and the visitor has not given it): sessions, clicks on results, products added to the cart from the results, with the same random session identifier. The identifier is stored in the browser's local storage for 24 hours; no cookies are set.
* As with any web request, the visitor's IP address and browser user agent reach Koply's servers.

**2. Order reporting, from the order received page**

If "Report orders" is enabled (it is by default), the order received page sends to `https://api.koply.eu/api/v1/events/order`: the order number, total, currency, and for each line the product id, quantity and unit price, together with the random session identifier. No name, email, address or other customer data is sent.

**3. Feed download, from Koply's servers**

Koply downloads your product feed from your store (`https://your-store/?koply-feed=…`) to index your catalog. The feed contains product data that is already public in your store.

**4. API key check, from your server**

Once an API key is saved, your server calls `https://api.koply.eu/api/v1/config` with that key to tell you whether it is valid: when you save it, when you press "Check again", and when you open the plugin settings page (at most once every 12 hours). Nothing else is sent. Nothing is sent to Koply before you save an API key.

* Terms of Service: https://koply.eu/terms
* Privacy Policy: https://koply.eu/privacy

== Installation ==

1. Upload the `koply-search-for-woocommerce` folder to `/wp-content/plugins/`, or install it from the WordPress plugin directory.
2. Activate the plugin through the **Plugins** menu. WooCommerce must be active.
3. Go to **WooCommerce → Koply Search** and follow the three steps.

== Frequently Asked Questions ==

= Do I need a Koply account? =

Yes. The free plan is permanent (1 site, 100 products) and paid plans include a 14-day trial with no credit card.

= Does it change my theme? =

No. The widget attaches to your search box and shows the results in an overlay as the shopper types. If your search box is not an `input[type=search]`, set its CSS selector in the plugin settings or in the Koply panel.

= My theme has its own add to cart logic. =

Set `window.KoplyCartHandled = true` before the plugin script loads and listen to the `koply.cart.add` event (it carries `entity_id`, `id` and `qty`). You can also turn off the plugin handler with the `koply_cart_handler_enabled` filter.

= Do I need cookie consent? =

Koply sets no cookies. It stores a random identifier in local storage for 24 hours to connect a search with the click and the order that follow it. If your legal advice says you need consent for this, choose "Wait for consent from my cookie banner": search keeps working, and measurement starts when your banner grants the statistics category through the WP Consent API, or when your site calls `Koply.setConsent(true)`.

= Are variations listed? =

By default each product is one result, with the lowest price of its variations. You can list each variation as a separate result in the settings; each one counts as a product for your plan limit.

= How often is the feed updated? =

Every hour if your catalog changed, and at least once a day. You can also press "Generate now". Koply downloads it on its own schedule.

= Can I change what goes into the feed? =

Yes, with the `koply_feed_query_args` filter (which products) and the `koply_feed_item` filter (the data of each product).

== Screenshots ==

1. Search results as the shopper types, with typo tolerance.
2. Setup page in WooCommerce → Koply Search.

== Changelog ==

= 1.0.0 =
* Initial release: product feed, search widget, add to cart from results and order reporting.
