=== Storzen AI Recommendations for WooCommerce ===
Contributors: devhasib
Tags: woocommerce, recommendations, upsell, cross-sell, personalization
Requires at least: 6.6
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 1.0.4
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
WC requires at least: 8.0
WC tested up to: 9.9

AI-powered WooCommerce product recommendations — frequently bought together, cart cross-sells, related products AI, and post-purchase upsells.

== Description ==

**Storzen AI Recommends for WooCommerce** is an AI-powered product recommendation engine that helps WooCommerce stores increase average order value (AOV), boost conversions, and deliver a personalized shopping experience — all without a single external API call, cloud subscription, or third-party dependency.

The built-in AI runs entirely on your WordPress server using your own WooCommerce order history. Smarter recommendations. Zero privacy risk. No monthly fees.

 🚀 **Boost AOV with Frequently Bought Together, Cart Cross-Sells, Post-Purchase Upsells, and AI-Ranked Related Products — all in one plugin.**
📖 **[ Documentation](https://webtend.net/docs/ai-recommends.html)**


---

### Why Storzen AI Recommends?

Most recommendation plugins depend on expensive cloud AI services or are limited to simple category-based suggestions. Storzen AI Recommends is different:

* ✅ **True on-site AI** — co-purchase frequency matrix built from your real order data
* ✅ **No API key required** — works out of the box, zero configuration to get started
* ✅ **No external data sharing** — 100% GDPR-friendly, all data stays in your database
* ✅ **Works on day one** — taxonomy-based fallback for new stores with no order history
* ✅ **Performance-first** — transient caching, sessionStorage tracking, page-specific asset loading
* ✅ **Works with any theme** — uses WooCommerce hooks and filters, no template overrides

---

### Core Features

**🛍️ Frequently Bought Together**

Show Amazon-style "Customers who bought this also bought" bundles on single product pages. Powered by a real co-purchase frequency matrix built from your WooCommerce order history. Supports configurable bundle discounts — percentage or fixed — to incentivize multi-product purchases and increase cart value instantly.

**🤖 Related Products AI**

Replace WooCommerce's generic default related products with AI-ranked, intent-driven suggestions. Choose from three scoring modes:

* **Co-purchase mode** — products frequently bought together rank highest
* **Taxonomy mode** — scoring based on shared categories and tags
* **Hybrid mode (default)** — blends both signals (70% co-purchase / 30% taxonomy) for the best results at any store maturity level

Overrides WooCommerce output via the official `woocommerce_related_products` filter — no template files modified, zero theme conflict risk.

**🛒 Cart Recommendations & Mini-Cart Cross-Sells**

Display smart product suggestions on the cart page and inside the mini-cart sidebar — exactly when purchase intent is highest. Products are scored in real time based on current cart contents and automatically exclude items already in the cart.

**🎉 Post-Purchase Recommendations**

Show a "Complete your purchase" widget on the WooCommerce order-received (thank-you) page. Seeds recommendations from the highest-value item in the completed order and automatically excludes already-purchased products. Catches customers at peak satisfaction — their most likely moment to buy again.

**👁️ Recently Viewed Products**

Session-based browsing history widget — fully GDPR-compliant with zero database queries. Uses browser `sessionStorage` (not cookies), data is never sent to the server, and clears automatically when the tab closes. Appears on product pages, the cart page, and anywhere via the `[sprwoo_recently_viewed]` shortcode.

**⭐ Social Proof Badges**

Automatically display trust signals on all recommendation cards — no manual setup needed:

* **Sales velocity** — "12 sold this month"
* **Rating summary** — "★ 4.8 · 240 reviews"
* **Total purchase count** — "1,240 people bought this"

All data sourced directly from WooCommerce. Fully configurable minimum thresholds so new stores never show misleading social proof.

**🔥 Low Stock Urgency Badges**

Trigger purchase urgency with automatic "Only 3 left!" stock badges on recommendation cards. Works with simple and variable products. Two display styles: quantity count ("Only X left!") or simplified ("Low stock"). Configurable stock threshold. Appears across all recommendation surfaces — FBT, related products, cart, post-purchase, recently viewed, Gutenberg block, and Elementor widget.

**📊 Built-in Analytics Dashboard**

Track recommendation performance directly inside WP Admin. Monitor impressions, clicks, and add-to-cart events for every recommendation widget. Filter by 7, 30, or 90-day windows. See exactly which products your AI is driving to cart — no third-party analytics tool required.

**🧱 Gutenberg Block**

Native WordPress block with server-side rendering. Place the recommendations widget on any page or post from the block editor. Configure recommendation type, column count, max products, title text, and toggle price, rating, and add-to-cart button visibility — all from the block sidebar.

**⚡ Elementor Widget**

Drop the Smart Recommendations widget into any Elementor layout with live canvas preview. Built-in style controls for title color and spacing. No shortcodes needed.

---

### How the AI Engine Works

1. Every time a WooCommerce order is completed, the co-purchase frequency matrix updates automatically.
2. Products purchased together more often receive higher recommendation scores.
3. On new stores with no order history, a taxonomy-based fallback uses shared categories and tags to generate relevant suggestions immediately — no cold-start dead zone.
4. The default hybrid mode blends co-purchase data and taxonomy signals (70/30 weighting) for optimal accuracy at every stage of store growth.
5. All scores are cached as WordPress transients (1-hour TTL) — the scoring query runs at most once per hour per product.

---

### Privacy & GDPR Compliance

* No data is ever sent to external servers
* Recently viewed tracking uses browser `sessionStorage` — no cookies, no personal data stored server-side
* All AI scoring, analytics, and recommendation data stays entirely within your WordPress database
* Full uninstall cleanup — both custom DB tables and all plugin options are removed when you delete the plugin

---

### Shortcode Reference

`[sprwoo_recently_viewed]` — Display recently viewed products anywhere.

**Optional attributes:**
* `max` — Number of products to show (default: 6)
* `columns` — Grid columns (default: 4)
* `title` — Widget heading text (default: "Recently viewed")

**Example:** `[sprwoo_recently_viewed max="4" columns="2" title="Your browsing history"]`

---

### Developer Notes

* All elements use prefixed `.sprwoo-` class names — no CSS conflicts
* Override styles via `public/css/sprwoo-public.css` from your theme
* Compatible with all properly coded WooCommerce themes and page builders
* HPOS (High-Performance Order Storage) compatible
* Full translation support — text domain: `storzen-ai-recommends`

---

### Compatible With

* All standard WooCommerce themes (Storefront, Astra, Flatsome, OceanWP, Divi, GeneratePress, and more)
* Block themes and FSE (Full Site Editing)
* Elementor, WPBakery, Divi Builder
* WooCommerce HPOS (High-Performance Order Storage)
* Simple products, variable products, grouped products

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/storzen-ai-recommends`, or install directly from the WordPress plugin screen.
2. Activate the plugin through **Plugins → Installed Plugins**.
3. Ensure WooCommerce is installed and activated.
4. Navigate to **Storzen Reco** in your WordPress admin sidebar to configure modules and settings.
5. For best results on existing stores: click **"Rebuild co-purchase matrix"** after activation to index your full order history immediately.

== Frequently Asked Questions ==

= Does this plugin require an API key or external service? =

No. Storzen AI Recommends works entirely within your WordPress installation using your own WooCommerce order data. No external API, no cloud service, no subscription, and no account required — ever.

= How accurate are the AI recommendations? =

Accuracy improves directly with order volume. On stores with hundreds of orders, the co-purchase matrix produces highly relevant recommendations. On brand-new stores, the built-in taxonomy fallback uses category and tag overlap to generate useful suggestions from day one. The default hybrid mode blends both signals for the best output at every stage of store growth.

= Does it work with variable products? =

Yes. The recommendation engine works with all WooCommerce product types — simple, variable, grouped, and external. Variable products in recommendation widgets link to the product page so customers can choose their variation. The low stock urgency badge checks all available variations and shows the lowest remaining stock count.

= How does the recently viewed feature stay GDPR compliant? =

Recently viewed products are stored exclusively in the browser's `sessionStorage` — a temporary, client-side mechanism that is never transmitted to the server and is automatically cleared when the browser tab closes. No personal data is written to the database. No cookies are used.

= Will it slow down my store? =

No. Recommendation scores are cached as WordPress transients with a 1-hour TTL — the AI scoring query runs at most once per hour per product, not on every page load. Social proof sales velocity data is cached for 6 hours. Frontend assets (CSS/JS) are loaded only on pages where recommendation widgets are active. The recently viewed feature triggers zero server-side queries.

= Does it conflict with my theme or other plugins? =

Storzen AI Recommends uses only standard WooCommerce hooks and filters. Related products are replaced via the official `woocommerce_related_products` filter — no template files are modified. This makes it fully compatible with any properly built WooCommerce theme.

= How do I place recommendations on a custom page? =

Use the native **Gutenberg block** or **Elementor widget** to drop recommendations anywhere without writing code. For recently viewed products specifically, use the `[sprwoo_recently_viewed]` shortcode.

= Can I customize the look of the recommendation widgets? =

Yes. All widget elements use prefixed `.sprwoo-` CSS class names to avoid conflicts. Override any style via your theme's `style.css` or a custom CSS plugin by targeting the `.sprwoo-` namespace.

= What database tables does the plugin create? =

Two custom tables are created on activation:
* `{prefix}sprwoo_copurchase` — stores the co-purchase frequency matrix
* `{prefix}sprwoo_analytics` — stores impression, click, and add-to-cart events

Both tables are fully removed on plugin deletion. The analytics table auto-purges rows older than your configured data retention window.

= What happens to my data if I uninstall the plugin? =

When you delete the plugin from the WordPress admin, the uninstall routine automatically drops both custom database tables, deletes all plugin options, and clears all transient cache entries. No manual database cleanup is required.

= How does the social proof badge threshold work? =

Each badge type has a configurable minimum threshold in the admin settings. For example, if the sales velocity threshold is set to 5, the "sold this month" badge only appears on products with at least 5 sales. This prevents new or low-volume products from showing misleading social proof.

= How does the low stock badge decide what to show? =

The badge appears when WooCommerce stock management is enabled for a product and the remaining stock is at or below your configured threshold (default: 5). For variable products, it checks all available variations and displays the lowest stock count. Products without stock management enabled are never shown a low stock badge.

== Screenshots ==

1. Admin analytics dashboard — real-time impressions, clicks, add-to-cart metrics, top recommended products table, clicks-by-module breakdown, and AI engine status panel with one-click co-purchase matrix rebuild.
2. Frontend product page showing the AI-powered Frequently Bought Together bundle widget with social proof badges (sales velocity, verified purchases, low stock urgency) and AI Recommended related products grid below.
3. Admin settings panel showing per-module configuration — toggle each recommendation engine on/off, set widget titles, adjust column count, max product limits, and price/rating/add-to-cart display options from a single clean tabbed interface.

== Changelog ==

= 1.0.4 =
* Improvement: All public and admin JavaScript rewritten to vanilla ES6 — zero jQuery dependency across all modules (FBT, cart, admin, recently viewed). Fully compatible with jQuery-free themes and modern WordPress setups.
* Improvement: Inline `style="display:none"` replaced with CSS class `.sprwoo-rv-hidden` for WPCS compliance.
* Improvement: Admin dashboard Pro upgrade card cleaned up — replaced arbitrary revenue estimate with an honest feature list and CTA. No fabricated data shown to users.
* Fix: Analytics `track_event` AJAX handler now correctly accepts all valid contexts — `post_purchase`, `recently_viewed`, `trending`, `checkout`, `on_sale`, `top_rated`, `category`, and `cross_sells` were previously missing from the allowlist, causing 400 errors for those modules.
* Fix: `extract()` removed from `SPRWOO_Frequently_Bought::load_template()` — replaced with an explicit closure-based variable scope to satisfy WordPress coding standards.
* Fix: `blocks/block.json` now declares `"render": "file:./render.php"` — aligns block registration with WordPress block API best practices.
* Fix: `NoCaching` phpcs:ignore annotation added to analytics INSERT query.
* Fix: `phpcs:disable` docblock added to admin view templates for local variable scope.

= 1.0.3 =
* New: Complete the Look — automatically displays WooCommerce cross-sell products on single product pages. Uses WC's native Linked Products → Cross-sells data. Zero extra DB queries, zero new meta keys. Configurable title, columns, max products, price/rating/ATC toggles. Also available via `[sprwoo_cross_sells]` shortcode with optional `product_id` attribute.
* New: Sale Countdown Timer — real-time "⏰ Sale ends in Xh Xm" badge on On-Sale product cards. Reads WooCommerce native sale end date. Countdown runs entirely in the browser — zero server load. Pulses red when under 1 hour remaining. Auto-removes from DOM when sale expires. Products without a sale end date are unaffected.
* New: Settings panels for Complete the Look and Sale Countdown Timer modules.
* Improvement: Admin dashboard Pro upgrade card updated with a clean feature list and direct CTA — no estimated revenue shown.

= 1.0.2 =
* New: On-Sale Products module — `[sprwoo_on_sale]` shortcode displays all products currently on sale with automatic discount-percentage badges (−30%). Powered by WooCommerce's native `wc_get_product_ids_on_sale()` — no custom queries. Transient-cached 2 hours, auto-busts on product save.
* New: Top Rated Products module — `[sprwoo_top_rated]` shortcode displays highest-rated products ordered by WooCommerce average rating. Configurable minimum rating (default 4.0) and minimum review count (default 3) thresholds prevent low-data products from appearing. Cached 4 hours, busts on review approval.
* New: Category Recommendations module — automatic "More from {Category Name}" widget on single product pages. Pulls products from the current product's primary category, excludes the current product, ordered by popularity. Dynamic title injects the real category name. Best-in-class fallback for new stores with no order history. Cached 2 hours per product.
* New: All three modules support social proof badges, low stock urgency badges, price, rating, and add-to-cart button toggles from Settings.
* New: Three new settings panels — On-Sale Products, Top Rated, Category Recommendations.
* New: Admin sidebar updated with three new module entries.
* Improvement: On-sale discount badge uses red (#e11d48) for high visual contrast and clear urgency signaling.

= 1.0.1 =
* New: Trending Products module — displays a "Trending Now" widget on the shop page and via the `[sprwoo_trending]` shortcode. Products scored by real sales velocity (units sold in the last 7, 14, or 30 days). Automatic bestseller fallback for new stores. Transient-cached, 2-hour TTL.
* New: Bestsellers widget — shortcode `[sprwoo_bestsellers]` renders all-time top sellers ordered by WooCommerce total_sales. Cached 6 hours.
* New: New Arrivals widget — shortcode `[sprwoo_new_arrivals]` renders recently published products with configurable look-back window (default 30 days). Cached 1 hour. Displays a "NEW" badge on each product card.
* New: Checkout Recommendations — compact AI-powered "You may also like" widget inside the WooCommerce order review table on the checkout page. Max 3 products, scored from current cart contents, excludes in-cart items. Designed to increase AOV without disrupting checkout completion.
* New: All three new modules support social proof badges, low stock urgency badges, price, rating, and add-to-cart toggles from Settings.
* New: Three new settings panels added — Trending Products, Bestsellers & New Arrivals, Checkout Recommendations.
* Improvement: Admin sidebar navigation updated with three new module entries.

= 1.0.0 =
* Initial release.
* Frequently Bought Together widget with configurable bundle discount (percentage and fixed amount).
* Related Products AI — co-purchase, taxonomy, and hybrid scoring modes (70/30 default blend).
* Cart Recommendations widget for cart page and mini-cart sidebar.
* Basic analytics dashboard — impressions, clicks, and add-to-cart tracking with date filters.
* Recently Viewed Products — sessionStorage-based, GDPR-safe, zero server-side DB queries.
* Post-Purchase Recommendations on the WooCommerce order-received page.
* Social Proof Badges — sales velocity, rating summary, and total purchase count.
* Low Stock Urgency Badges — configurable threshold, quantity and simple display modes.
* Native Gutenberg block with server-side rendering and full sidebar controls.
* Elementor widget with live canvas preview and built-in style controls.
* Modern admin UI — left sidebar navigation, metric cards, toggle settings, module management.
* Full translation support — text domain `storzen-ai-recommends`, all strings wrapped and ready.

== Upgrade Notice ==

= 1.0.4 =
Bug fix release — fixes analytics tracking errors for post-purchase, recently viewed, trending, and checkout modules. No database changes. Safe to update.

= 1.0.3 =
Adds Complete the Look (cross-sell widget on product pages) and Sale Countdown Timer. No database changes. Safe to update — new modules are enabled by default and configurable from Settings.

= 1.0.2 =
Adds On-Sale Products, Top Rated, and Category Recommendations modules. No database changes. Safe to update — new modules are enabled by default and configurable from Settings.

= 1.0.1 =
Adds Trending Products, Bestsellers, New Arrivals, and Checkout Recommendations modules. No database changes. Safe to update — activate and configure the new modules from Settings.

= 1.0.0 =
Initial release of Storzen AI Recommends for WooCommerce. Install and run the co-purchase matrix rebuild for best results on existing stores.
