=== Arugula ===
Contributors: epyphite
Tags: search, offers, recommendations, affiliate, contact form
Requires at least: 5.7
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 0.2.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Shows offers that fit what your visitors search for, beside your own search results, each with a tracked link.

== Description ==

Arugula attaches to the search box your site already has. When a visitor searches, the search words go to Arugula, which finds offers that fit. Up to a handful appear under your search form, or in an element you choose, each with the shop it comes from and a link to the offer.

* Works with the standard WordPress search (`?s=`) and most theme search forms, with nothing to set up.
* No account is needed, and the search script sets no cookies. It keeps an anonymous session token in the visitor's browser storage (localStorage). On WooCommerce stores, a visitor who arrives from an Arugula link gets a WooCommerce session, which uses WooCommerce's own cookie, so the purchase can be reported (see External services).
* When nothing fits, nothing is shown.
* Arugula is a matching engine: offers are ranked by fit only, never by payment. Under the offers, visitors see: "Ranked by fit only. Arugula may earn a commission if you buy through these links, at no extra cost to you." Beside it, Arugula's search script shows a small "by Arugula" line with the Arugula icon. Both lines are always shown: your theme can restyle them but not remove them. The plugin itself adds no credit or link.
* Optional: pass on the message of Contact Form 7, WPForms and Gravity Forms submissions as a request for offers. This is off by default. Only the message text is sent, with email addresses and phone numbers removed.
* On WooCommerce stores, the plugin can also claim your store in Arugula with an Ed25519 key exchange. Your products can then be synced as offers from Arugula, and purchases by visitors who came from Arugula are reported back to it.

By using Arugula you agree to arugulanet.com/terms. Privacy: arugulanet.com/privacy.

== External services ==

This plugin relies on Arugula, a service run by Epyphite, to find offers. Everything below is what the shipped code sends and stores.

**The search script, in the visitor's browser**

* On every front-end page, the plugin loads `https://api.arugulanet.com/embed/v0.5.2/search.js`. Its Subresource Integrity hash pins it.
* **When it sends.**
  * Automatically when a page loads with a search already in it: a search parameter in the address (`s`, `q`, `search`, `query`, `search_query`, or the name of your search box), or text already in the search box. A results page is the usual case.
  * When a visitor searches without leaving the page.
  * It sends nothing for searches shorter than 3 characters, or for the same search sent just before on that page.
* **What it sends**, to `https://api.arugulanet.com/v1/...`, with no cookies:
  * the search words;
  * the page's address (`page_url`, the full address including its query string, without the `#` part);
  * the page's title (`page_title`, up to 300 characters);
  * the page's language, when the page declares one;
  * the channel `wordpress`.
* **How it fetches offers.** On the first request it asks for an anonymous session. Then it asks for the offers that fit, every 1.5 seconds for up to 30 seconds.
* **What it stores** in the visitor's browser: the anonymous session token and its expiry, in localStorage under `adagent.session:https://api.arugulanet.com:wordpress`. It is reused until it expires, and removed if the service refuses it.
* **What the service keeps.** Arugula's API contract says it keeps the session token only as a hash, with the channel, and stores no IP address or user agent for these sessions. Offer links go through `https://api.arugulanet.com/r/...`, which records the click (channel, request, offer, time and a coarse client type) and then sends the visitor to the offer. That redirect sets no cookie.

**Contact forms (only when you turn them on)**

* After a Contact Form 7, WPForms or Gravity Forms submission, your server sends one field's text to the same API, in the background (WP-Cron).
  * That field is the longest field whose name or type looks like a message (message, comment, enquiry, inquiry, request, details, textarea).
  * Email addresses and phone numbers are removed first, and the text is cut to 2,000 characters. No other fields are sent.
* Your server keeps its own anonymous session token in a WordPress transient.

**WooCommerce store (only after you claim it in Arugula)**

* **Claim.** Arugula reads `/wp-json/adagent/v1/claim`, which answers with the claim ID, the claim token, the store's Ed25519 public key and a signature.
* **Products.** Your Arugula account reads `/wp-json/adagent/v1/products` to sync offers; the claim token protects it. It returns up to 50 published products: name, short description (or description) up to 60 words, price, store currency and link.
* **Click ID.** A visitor who arrives with `?adagent_click=` from an Arugula link gets a WooCommerce session, which uses WooCommerce's cookie, holding that click ID. The click ID is then saved on their order.
* **Purchase report.** For such orders your server sends Arugula the click ID, the order number, the order total, the currency, the status and the time. The status is approved on payment, and rejected on refund or cancellation. It goes to the postback URL Arugula gave you, signed with your secret.

Terms of use: https://arugulanet.com/terms/
Privacy policy: https://arugulanet.com/privacy/

== Installation ==

1. Upload the `arugula` folder to `/wp-content/plugins/`, or install the zip from Plugins > Add New > Upload Plugin.
2. Activate the plugin.
3. Optional: under Settings > Arugula, set your search box or where offers show, and turn on contact forms.

== Frequently Asked Questions ==

= Do I need an Arugula account? =

No. The plugin uses an anonymous session.

= My search box is not found =

Set its CSS selector under Settings > Arugula, for example `input[name=s]`.

== Screenshots ==

1. Offers that fit the visitor's search, under your site's own search box. Each card shows the shop it comes from and links to the offer.
2. The offer cards end with the disclosure, "Ranked by fit only. Arugula may earn a commission if you buy through these links, at no extra cost to you.", and the "by Arugula" line.

== Changelog ==

= 0.2.1 =
* Loads embed v0.5.2: each offer shows the shop it comes from ("from Charles & Keith · charleskeith.com"), as text. The link stays the tracked one.
* Screenshots in the readme.

= 0.2.0 =
* WooCommerce: store claim, product list for offer sync, purchase postback.

= 0.1.0 =
* First release: site search offers, settings page, contact-form requests.
