=== MerchantStamp Catalog Audit for WooCommerce ===
Contributors: arnaud92
Tags: woocommerce, structured-data, json-ld, product-feed, ai
Requires at least: 6.0
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 1.0.5
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Audit your WooCommerce catalog, enrich missing product schema, and publish AI-ready feeds for modern search, shopping agents, and structured product discovery.

== Description ==

**MerchantStamp Catalog Audit is the AI-readiness layer for WooCommerce catalogs.**

It helps merchants audit catalog quality, enrich missing product schema, and publish AI-ready feeds — without replacing their existing SEO or feed plugin.

Unlike traditional feed plugins focused on channel exports, this plugin focuses on **catalog completeness and machine readability** for modern AI-driven discovery.

= Fully functional, free, and offline-first =

This plugin is **100% functional locally**. Every feature listed below runs on your server with no external service required. There is no time limit, no product cap, no locked feature behind a license key.

* Full ShopScore audit (no product limit)
* Field Coverage Analytics
* Top Issues panel (the fields with the most missing values, ranked)
* Prioritized Recommendations (actions ranked by estimated ShopScore gain)
* JSON-LD enrichment on top of Yoast, Rank Math, or native WooCommerce
* `products.jsonld` feed (schema.org Product catalog)
* `llms.txt` feed (LLM-friendly catalog summary)
* `acp.json` feed (Agent Commerce Protocol)
* `agent.json` feed (with SHA-256 content-integrity proof)
* Scan history archive (60 most recent scans)
* Score Trend sparkline
* Compare any two scans (delta score, delta critical missing, per-field coverage diff)
* Degradation alerts (banner when ShopScore drops or critical-missing rises)
* Automatic feed rebuild on product create / update / delete / stock change
* WooCommerce admin dashboard
* Full HPOS compatibility

= Optional external service =

The plugin can **optionally** connect to the MerchantStamp service for capabilities that genuinely require a centralized backend. The plugin works entirely without it.

What the service adds (Guideline 6 — Serviceware):

* **Centralized multi-site dashboard** — manage catalog quality across multiple WooCommerce stores from one place
* **Cross-site verification key** — published at `merchantstamp.com/.well-known/keys/<slug>`, referenced inside `agent.json` so AI agents can verify the integrity of your published feed against a public key you control
* **Storefront discovery loader** — a small JavaScript snippet (versioned, SRI-protected, opt-in) injected in the footer that helps AI agents find this site's feeds at scale
* **Advanced alerting** — Slack and email delivery of degradation alerts, beyond the in-admin banner that this plugin shows for free
* **Push notifications** to your MerchantStamp dashboard after each rebuild

Pricing for the MerchantStamp service is at [merchantstamp.com](https://merchantstamp.com).

= Built to work alongside your stack =

* Yoast SEO / Yoast WooCommerce SEO
* Rank Math / Rank Math PRO
* AIOSEO
* Google for WooCommerce
* Product Feed PRO for WooCommerce
* Any WooCommerce-compatible theme

If another plugin already outputs valid schema, this plugin does **not overwrite it**. It fills missing fields only.

= Read-only by design =

This plugin does not rewrite your WooCommerce product catalog. It reads your product data, computes scores, enriches structured output at render time, and generates feed files from existing catalog data.

= External services =

This plugin connects to MerchantStamp services **only when the user enters an API key**. Without an API key, no external connection is ever made.

When a user enters a MerchantStamp API key, the plugin connects to:

**1. MerchantStamp Activation & Push API**

* Endpoint: `https://merchantstamp.com/api/webhooks/plugin`
* Purpose: Validate the API key on activation, and report feed-build status after each rebuild so the merchant's MerchantStamp dashboard stays in sync.
* Data sent: site URL, plugin version, WordPress version, WooCommerce version, the merchant's chosen slug, public feed URLs, total product count, average ShopScore, build duration in milliseconds, and a UTC timestamp.
* No personal data, customer data, or order data is ever sent.
* Terms of service: https://merchantstamp.com/en/legal
* Privacy policy: https://merchantstamp.com/en/privacy

**2. Optional Storefront Loader Script**

* URL: `https://merchantstamp.com/js/silver-loader.v1.0.0.js`
* Purpose: A small JavaScript file injected in the site footer (only when an API key is entered AND the filter `msca_inject_loader` is true) that helps AI discovery systems find this site's published feeds.
* Source code: https://github.com/arnaud-92/silver-loader
* Subresource Integrity: loaded with an SRI hash so the browser refuses to execute any modified copy.
* Opt-out: site owners can disable the loader injection at any time by adding the following filter:

`add_filter( 'msca_inject_loader', '__return_false' );`

= Privacy =

* Without an API key entered, this plugin sends no data to any external service.
* With an API key, the plugin sends only operational metadata listed in the **External services** section above.
* No customer data, order data, email addresses, IP addresses, or other personal information is collected, stored, or transmitted by this plugin.
* All generated feed files contain only public product information already published on the merchant's WooCommerce store.
* Plugin settings are stored in the standard WordPress options table; no custom database tables are created.
* Scan history and cache are stored under `wp-content/uploads/merchantstamp-catalog-audit/private/` (created with index.php silencers and `.htaccess` denial rules).

== Installation ==

1. Upload the `merchantstamp-catalog-audit` folder to `/wp-content/plugins/`, or install via **Plugins → Add New** and search for "MerchantStamp Catalog Audit".
2. Activate the plugin in the WordPress admin.
3. Open **MerchantStamp Catalog Audit** in the admin sidebar.
4. Run your first catalog scan.
5. Review your ShopScore, Top Issues, and Recommendations.
6. Generate or rebuild feeds.
7. *(Optional)* If you want the centralized multi-site dashboard and the storefront loader, enter a MerchantStamp API key from [merchantstamp.com](https://merchantstamp.com).

**Requirements:**

* WordPress 6.0 or higher
* WooCommerce 7.0 or higher
* PHP 7.4 or higher
* Pretty permalinks enabled (for public feed URLs)

== Frequently Asked Questions ==

= Do I need a MerchantStamp account to use this plugin? =

No. Every feature runs locally on your WordPress server with no external service required. The plugin is fully usable without ever creating an account.

= What does the MerchantStamp service add that this plugin can't do alone? =

The plugin can audit, enrich, and publish AI-ready feeds entirely on its own. The MerchantStamp service adds capabilities that genuinely require a centralized backend: multi-site dashboard across many stores, cross-site verification key publication, advanced Slack/email alerting, and a CDN-hosted storefront loader. None of these can be done by a single WordPress install on its own.

= Does this plugin modify my WooCommerce product data? =

No. It is read-only with respect to WooCommerce product records.

= Does it replace Yoast SEO or Rank Math? =

No. It works alongside them. If your SEO plugin already outputs structured product data, this plugin fills common gaps instead of replacing the schema layer.

= Will feeds rebuild automatically? =

Yes. The plugin detects product create/update/delete and stock changes, and schedules feed rebuilds automatically using WP-Cron with a 60-second debounce.

= How many products can it scan? =

Unlimited. The plugin paginates through your entire catalog regardless of size.

= How do I disable the optional external loader script? =

The loader is only injected when (1) a MerchantStamp API key is entered AND (2) the filter `msca_inject_loader` returns true. To disable explicitly:

`add_filter( 'msca_inject_loader', '__return_false' );`

= Can I uninstall safely? =

Yes. Uninstalling removes plugin settings, the private cache directory, and the scan history. Your WooCommerce product data is not changed. Public feed files in `wp-content/uploads/merchantstamp-catalog-audit/feeds/` are intentionally preserved (in case AI agents still reference them) — you can delete them manually if desired.

= Is it compatible with HPOS (High-Performance Order Storage)? =

Yes. The plugin declares HPOS compatibility and does not interact with the orders table.

== Screenshots ==

1. ShopScore overview — average score, products with critical fields missing, last scan date.
2. Field Coverage — per-field coverage with color-coded bars.
3. Top Issues — ranked list of fields with the most missing values, critical flag.
4. Recommendations — prioritized actions with estimated ShopScore gain.
5. Score Trend & Scan History — sparkline + scan-by-scan log with one-click compare.
6. Compare two scans — delta score, delta critical missing, per-field coverage diff.

== Changelog ==

= 1.0.5 =
* Fixed Plugin URI to point to the live English product page: https://merchantstamp.com/en/platforms/woocommerce (previous URL was a 404).

= 1.0.4 =
* Updated Plugin URI to a dedicated product page: https://merchantstamp.com/en/platforms/woocommerce
* Updated legal links in readme: Terms → /en/legal, Privacy → /en/privacy
* Softened user-facing wording: "Pro activated!" → "MerchantStamp service connected"

= 1.0.3 =
* Fixed a file integrity issue: removed 147 trailing NUL bytes from class-feeds.php that caused a PHP parse error.
* All PHP files now pass `php -l` cleanly (verified with PHP 8.2).
* Aligned all internal plan references on "free" (previously some branches in the API key sync reset to "bronze", creating an inconsistency with the rest of the codebase).
* Cleaned legacy comments that referred to "Silver / Gold" or "F6 / F7" for features that are now fully local and free.

= 1.0.2 =
* Cosmetic cleanup of stale code comments referring to "(Pro)" or "Bronze+" labels for features that are now fully local and free.
* No functional change vs 1.0.1 — all local features remain unconditionally enabled.

= 1.0.1 =
* All "Pro" features unlocked in the plugin: ACP feed, agent.json, scan history, compare, degradation alerts, score trend.
* Removed the "Free limit reached" badge and the upgrade banner from the admin (Guideline 11 compliance).
* The plugin is now 100% functional locally, 