=== CookPal Reader Engagement ===
Contributors: whimziai
Donate link: https://whimzi.ai/
Tags: recipe, cooking, ai, chat, assistant
Requires at least: 5.0
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.2.5
License: GPLv2 or later
License URI: http://www.gnu.org/licenses/gpl-2.0.html

Boost reader engagement on your food blog: an on-post chat that answers cooking questions from your content, with monthly analytics and tips.

== Description ==

**CookPal is a reader engagement tool custom-built for food bloggers. Instant answers for your readers. Clear insights and recommendations for you.**

CookPal bridges the gap between you and your audience. It adds a lightweight AI chat assistant to your recipe posts that answers reader questions instantly — and there are no generic answers here: every answer draws from your blog post, your recipe card and your expertise first. General cooking knowledge is only the fallback when the answer isn't on the page; your post is always the primary source.

Answering questions on the spot keeps readers on *your* site instead of losing them to search engines and other blogs. Readers stay on your post longer — more time on page, more ad impressions — and casual visitors turn into an engaged audience. Finally, a tool that works for both you and your readers.

Built by food bloggers, for food bloggers.

[Learn more at whimzi.ai](https://whimzi.ai/) | [See CookPal live on a SugarYums recipe](https://sugaryums.com/kimchi-burger/)

= For your readers =

* **Instant answers, right on your post** — ingredient swaps, timings, techniques, storage: answered on the spot, no scrolling away to search
* **Your content answers first** — every answer draws from your post and recipe card before general cooking knowledge, so readers get *your* method, *your* measurements and *your* tips
* **Discover more of your recipes** — when your post links to a related recipe, CookPal recommends it in the chat
* **Any language** — readers can ask questions in almost any language
* **Guardrails built in** — CookPal won't give medical advice and is careful with substitutions you haven't tested, so readers feel supported, understood and confident making your recipes

= For you =

* **More time on page** — readers who get instant answers stay longer: more engagement, more ad impressions
* **Respects your affiliate links** — product recommendations come from the links already in your post, with `nofollow`/`sponsored` attributes preserved
* **Opt-in analytics dashboard** — monthly chat volume, average chat time and your most-asked-about post, right in wp-admin (disabled by default; no personal reader data is collected)
* **CookPal Insights report** (Scale and Enterprise plans) — a personalised monthly report: which posts generate the most questions, where readers get stuck, and specific, plain-language recommendations for improving your content
* **WP Recipe Maker integration** — an optional "Need Help? Get Instant Answers!" button right in the recipe card opens the chat
* **Make it yours** — custom assistant name, greeting message, pop-up message and duration, input placeholder, and accent, hover and bubble colours to match your theme; button position and chatbox size are set independently for desktop and mobile
* **Show it where it belongs** — the chat appears on single posts only, and Visibility Settings let you exclude whole categories (sub-categories included)

= Fast and lightweight =

* Scripts load deferred and non-blocking, with zero Core Web Vitals impact
* Plays nicely with full-page caching plugins such as WP Rocket, W3 Total Cache and LiteSpeed Cache
* Set up in about ten minutes: install, paste your license key, customize, done

= Plans and pricing =

CookPal Reader Engagement is a Software as a Service (SaaS) plugin: the plugin is free and all of its code is fully functional GPL code, while the chat assistant is powered by the external Whimzi AI service, which requires a license. Plans start at $11.99/month, cancel any time:

* **Grow** — for blogs up to 100K monthly pageviews: the full chat experience, customization and a monthly engagement summary
* **Scale** — up to 1M monthly pageviews: everything in Grow, plus the monthly CookPal Insights analytics report with reader question themes and content recommendations
* **Enterprise** — beyond 1M monthly pageviews: scalable infrastructure, dedicated support and custom onboarding

See current pricing and full plan details at [whimzi.ai/buy-cookpal](https://whimzi.ai/buy-cookpal/). Use of the service is subject to the Whimzi AI [Terms of Use](https://whimzi.ai/terms) and [Privacy Policy](https://whimzi.ai/privacy).

= About Whimzi AI =

CookPal is built by [Whimzi AI](https://whimzi.ai/) — smart tools for creators, by creators — a member of the NVIDIA Inception program.

= Support =

For plugin questions, use the [support forum](https://wordpress.org/support/plugin/cookpal-reader-engagement/). For account and billing questions, reach us via [whimzi.ai](https://whimzi.ai/).

== Installation ==

1. Upload the `cookpal-reader-engagement` folder to the `/wp-content/plugins/` directory, or install directly through the WordPress plugins screen
2. Activate the plugin through the 'Plugins' menu in WordPress
3. Configure your API settings in the CookPal settings page
4. The CookPal chat button then appears automatically on single posts. Use the Visibility Settings on the CookPal settings page if you want to hide it on posts in specific categories.

== Frequently Asked Questions ==

= Do I need an API key to use CookPal? =

Yes, CookPal requires API credentials to connect to the Whimzi AI service. You can obtain these from your Whimzi AI account.

= Is CookPal free to use? =

The plugin itself is free, and all of its code is fully functional GPL code. The chat assistant, however, is powered by the Whimzi AI service, which requires a paid Whimzi AI license. See https://whimzi.ai/buy-cookpal/ for current plans.

= Which plans include the monthly analytics report? =

Every plan can use the opt-in analytics dashboard in wp-admin. The monthly CookPal Insights report — top reader questions by theme plus content-improvement recommendations — is available on the Scale and Enterprise plans.

= Can I customize the chat interface? =

Yes, CookPal provides customization options in the settings panel to match your site's design.

= What WordPress versions are supported? =

CookPal requires WordPress 5.0 or higher and PHP 7.4 or higher.

= What data does CookPal collect? =

CookPal connects to the Whimzi AI service to provide AI-powered cooking assistance. When users interact with the chat feature, their messages are sent to Whimzi AI servers for processing. So the assistant can answer questions about the post being viewed, CookPal also sends that post's content, its post metadata, and its approved comments - including public commenter display names, any comment author URLs, and star ratings - to the Whimzi AI service. Analytics data collection is separate, optional, and disabled by default - you can enable it in the plugin settings to help improve the service.

== Privacy Policy ==

CookPal Reader Engagement is a Software as a Service (SaaS) plugin that connects to external Whimzi AI servers to provide AI-powered cooking assistance.

**Data Collection and Usage:**

* **Chat Messages and Post Content**: When users interact with the CookPal chat widget, their messages are sent to Whimzi AI servers (https://cookpal-api.whimzi.ai) for processing and generating responses. So the assistant can answer questions about the post being viewed, CookPal also sends that post's rendered content, its post metadata, and its approved comments - including public commenter display names, any comment author URLs, and star ratings - to the same service. This is required for the plugin to function.

* **Analytics (Optional)**: If you enable analytics in the plugin settings, anonymous usage data (such as chat interactions and feature usage) may be sent to Whimzi AI analytics servers (https://analytics-api.whimzi.ai) to help improve the service. Analytics is **disabled by default** and requires explicit opt-in.

* **License Key**: Your license key is used to authenticate API requests and is stored in your WordPress database.

**User Consent:**

* By installing and activating CookPal, and configuring it with a license key, you consent to the chat service functionality.
* Analytics tracking requires explicit opt-in via the "Enable Analytics" checkbox in plugin settings.
* No tracking occurs unless you explicitly enable it.

**Third-Party Service:**

CookPal relies on Whimzi AI's external services. For more information, please review the Whimzi AI Terms of Use at https://whimzi.ai/terms and the Whimzi AI Privacy Policy at https://whimzi.ai/privacy

**Data Security:**

All communication with Whimzi AI servers is conducted over secure HTTPS connections.

== Screenshots ==

1. CookPal on desktop site with customized pop-up
2. CookPal recommending interlinked recipes
3. CookPal responding based on blog post information
4. CookPal recommending affiliate products linked in post
5. CookPal button in WPRM that opens chat
6. CookPal on mobile site with customized pop-up
7. CookPal welcome message on mobile
8. CookPal on mobile recommending affiliate products
9. CookPal settings and customizations
10. CookPal analytics dashboard
11. Monthly analytics report available on Scale and Enterprise plans

== Changelog ==

= 1.2.5 =
* WordPress.org review fixes. Output escaping: colour settings that flow into CSS context (the inline chat-button style and the admin colour previews) are now validated as hex colours instead of being run through esc_attr(), which is not a CSS-context escaper. Colours are also hex-validated before being sent to the front-end script and on save. Generic/global names: every registered setting, option group and admin menu slug now uses a hardcoded, statically-detectable "cookpal" prefix instead of being built at runtime, so the WordPress.org static analyser can verify the prefix. Option names are unchanged at runtime, so no settings are lost on upgrade. Also switched request bodies to wp_json_encode() and added strict validation of the analytics date-range/event-type parameters. Detailed-guidelines pass: a "Powered by Whimzi AI" credit now appears in the plugin's own admin pages while the front-end chat-window credit is opt-in and off by default (new setting), the Privacy Policy now fully discloses that post content, post metadata and approved comments are sent to the AI service, and the installation instructions were corrected (the chat appears automatically on single posts; there is no shortcode/widget). Security hardening: the public chat AJAX endpoints now reject any post ID that is not a published, publicly-viewable post (so draft/private/protected posts can no longer be read through them), the public analytics endpoint validates the event type against an allowlist, leftover debug logging was removed from the front-end script, and the translation template (.pot) was regenerated. Tested on a clean WordPress install with WP_DEBUG enabled. No changes to the chat or analytics behaviour for normal use.

= 1.2.4 =
* Updated the plugin description and short description to better reflect CookPal's reader-engagement focus. No functional changes to chat or analytics.

= 1.2.3 =
* Renamed to "CookPal Reader Engagement" for the WordPress.org directory and aligned the text domain to the new slug (`cookpal-reader-engagement`), clearing all Plugin Check text-domain warnings. Removed stray `.DS_Store` files from the package and an unused internal button-colour option. No changes to chat or analytics behaviour.

= 1.2.2 =
* Chat assistant now reads recipe-card content (e.g. WP Recipe Maker), so it can recommend products linked inside the recipe card, not just the post body. Affiliate link attributes (nofollow/sponsored) are preserved.

= 1.2.1 =
* WordPress.org compliance: updated "Tested up to" to 7.0 and removed stray `.DS_Store` files from the distribution package. No functional changes.

= 1.2.0 =
* Version jumped from 1.1.59 → 1.2.0 to reflect new user-facing features per semver. The internal version sequence used during WP.org compliance work (1.1.60–1.1.63) is summarised below for transparency.
* **New** "Assistant Name" setting in General Settings — customise the name shown at the top of the chatbox (max 20 characters; defaults to "CookPal" if blank).
* **New** "Visibility Settings" section in General Settings — exclude CookPal from posts in specific categories via a search-based chip picker. Selecting a parent category also excludes its sub-categories.
* **New** Analytics Opt-In card on the Analytics page; greyed-out dashboard now shows placeholders instead of leaking real data when opt-in is off.
* WordPress.org compliance pass (was 1.1.60–1.1.62 internally): full Plugin Check pass; ABSPATH guards; sanitisation sweep; output escaping; runtime-fetched CSRF nonce that survives page caching; Powered-by hyperlink removed; inline `<style>`/`<script>` blocks moved to enqueued resources.
* Stability fixes: chat icon visibility on cached sites; saving the opt-in no longer wipes other settings; blank button-offset / chatbox-dimension settings fall back to sensible defaults (300 / 80 / 350 / 400); admin assets cache-busted by file modification time; analytics dashboard renders defensively when API calls fail.

= 1.1.62 =
* Plugin Check cleanup: nonce verification now uses `check_ajax_referer()` directly so the static analyser sees it (functionally identical to the previous wrapper). Inline button CSS no longer uses heredoc syntax. CI-generated `build/constants.php` now includes the standard `ABSPATH` guard.

= 1.1.61 =
* Restored the "Enable Analytics" opt-in checkbox in the plugin settings page (below the Pop-up duration field). The setting was originally added in November but was inadvertently lost during a branch merge. With this release, the code now matches the Privacy Policy: analytics events only reach the analytics API when the site owner has explicitly opted in. Default remains off.

= 1.1.60 =
* Public AJAX endpoints now verify a CSRF nonce. The nonce is fetched at runtime via admin-ajax.php so it survives full-page caching (WP Rocket, W3 Total Cache, LiteSpeed, etc.).
* `track_event` analytics payload (`$_POST['data']`) is now recursively sanitized before being forwarded to the analytics API.
* Chat-button and popup-bubble CSS moved from a footer `<style>` block to `wp_add_inline_style` for Plugin Check compliance. Output is byte-identical; chatbox CSS still lazy-loads on click.
* Admin analytics nonce moved from an inline `<script>` to `wp_localize_script`.
* "Powered by Whimzi AI" attribution in the chatbox is now plain text (no external link).

= 1.0.0 =
* Initial release
* AI-powered chat interface
* Recipe and cooking assistance
* Meal planning features
* WordPress integration

== Upgrade Notice ==

= 1.2.5 =
Security and WordPress.org compliance update (output escaping + prefixing). Settings are preserved. Recommended for all installations.

= 1.1.60 =
Security and compliance update. Recommended for all installations.

= 1.0.0 =
Initial release of CookPal Reader Engagement.