=== Gold Standard Analytics for WooCommerce ===
Tags: woocommerce, laboratory, coa, analytics, product testing
Requires at least: 6.5
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Connect selected WooCommerce order lines to Gold Standard Analytics laboratory testing and keep authorized COA PDFs locally.

== Description ==

Gold Standard Analytics for WooCommerce provides an administrator-controlled bridge between a WooCommerce store and the Gold Standard Analytics laboratory service.

The plugin does nothing remotely on activation. A WooCommerce manager must first save a scoped GSA live API key and then deliberately select **Connect and register webhook**. Product edit screens configure exact testing mappings. GSA orders are created later, and only when a manager selects configured WooCommerce order line items in the order admin.

Features include:

* Non-autoloaded API credentials that are never rendered back after saving; `GSA_WC_API_KEY` in `wp-config.php` is also supported.
* Cached GSA categories, compounds, tests, bundles, and sample requirements.
* Exact product and variation mappings, including an optional explicit lot or batch value that is never inferred from SKU.
* Quote-first order creation with a deterministic line-item `clientReference` and API idempotency key.
* HPOS-compatible order access through WooCommerce APIs only.
* Signed, timestamped, raw-body HMAC webhook verification and durable event-ID deduplication.
* Fast webhook acknowledgement followed by a durable WP-Cron queue with bounded retry processing.
* Authorized published-result retrieval and local COA PDF sideloading to the WordPress Media Library.
* Fail-closed COA association: the remote GSA order ID, expected compound, and any configured lot/batch must match before public attachment. Mismatches remain private in a manual-review state.
* Hourly status polling as a webhook fallback and six-hour catalog refresh.
* Optional redacted WooCommerce operational logging, disabled by default.
* No telemetry, advertising, tracking pixels, or remote frontend assets.

WooCommerce must be installed and active.

== External service ==

This plugin connects to the Gold Standard Analytics Agent API at `https://www.goldstandardanalytics.com/api/v1/agent` only after an administrator explicitly connects it.

Depending on the action, it sends the API key, selected laboratory category/compound/tests, turnaround and raw-data preference, optional administrator-entered lot/batch, a site-derived client reference, WooCommerce order/line/product/variation identifiers in operational notes, and quantity. GSA uses this data to quote and create laboratory submissions, return statuses and authorized results, and deliver signed webhooks.

When an administrator selects **Connect and register webhook**, the plugin also sends the complete public webhook URL generated for the current site, normally `https://YOUR-WORDPRESS-SITE.example/wp-json/gold-standard-analytics/v1/webhook`, and requests subscriptions to `order.created`, `order.status_changed`, `order.cancelled`, `coa.published`, and `coa.retracted`. This lets GSA deliver those signed events to the store. The URL contains the store's public scheme, host, any WordPress subdirectory, and the `/wp-json/gold-standard-analytics/v1/webhook` REST path.

For a matched published result, the plugin directly follows the short-lived HTTPS COA URL returned by the authorized API; that file URL may be hosted on GSA-controlled Supabase Storage. The PDF is then stored on the WordPress site.

Use requires an active GSA customer account, accepted service terms, configured addresses, and a scoped live API key.

* Service: https://www.goldstandardanalytics.com/
* Privacy Policy: https://www.goldstandardanalytics.com/privacy
* Terms: https://www.goldstandardanalytics.com/terms

The fixed production base URL can be changed by a site developer with the `gsa_wc_api_base_url` filter. Doing so changes the external service destination and should be reviewed by the store owner.

== Installation ==

1. Install and activate WooCommerce.
2. Upload the plugin directory to `/wp-content/plugins/` or install the release ZIP in Plugins > Add New.
3. Activate **Gold Standard Analytics for WooCommerce**.
4. Open WooCommerce > Gold Standard Analytics.
5. Save a `gsa_live_` API key. Saving settings makes no network request.
6. Select **Connect and register webhook**. A public HTTPS WordPress REST URL is required.
7. Synchronize the catalog, then configure the **GSA Testing** panel on products or exact variations.
8. Open a WooCommerce order, select configured line items, and create their GSA testing orders.

WP-Cron must be able to run. On low-traffic or production sites, configure a real scheduler to request `wp-cron.php` regularly.

== Frequently Asked Questions ==

= Does activation contact GSA? =

No. Activation creates local non-autoloaded options and schedules local cron hooks. Only the explicit Connect action registers or rotates a webhook and synchronizes the catalog.

= Is a product saved as a GSA order? =

No. The product screen only saves testing configuration. A manager creates GSA orders later from selected, configured WooCommerce order line items.

= Is the product SKU used as a laboratory lot? =

No. Lot/batch is an optional dedicated field. If configured, it is sent and must match the published result exactly before the COA is attached.

= Where is the API key stored? =

By default it is held in a dedicated non-autoloaded WordPress option, masked in the UI, and never rendered back. For stronger operational control, define `GSA_WC_API_KEY` in `wp-config.php`; WordPress core does not provide a general-purpose secret vault.

= What happens if webhook delivery is delayed? =

Signed events are queued locally and retried by WP-Cron. An hourly authenticated status poll provides a fallback for mapped orders. Event IDs are retained for 30 days to deduplicate at-least-once delivery.

= What happens on uninstall? =

Uninstall removes plugin options, credentials, caches, mappings, product/order/item metadata, queued webhook records, scheduled hooks, and only those Media Library PDFs marked as plugin-managed. It does not contact GSA or delete remote laboratory orders. Deactivation alone preserves data.

== Privacy ==

The plugin proposes privacy-policy text under Settings > Privacy. Store owners are responsible for reviewing that text, their legal basis, retention obligations, and disclosures. Local order mappings and COAs may contain identifiers related to commercial laboratory submissions. Optional logs exclude bodies, credentials, and customer PII.

== Changelog ==

= 1.0.0 =
* Initial WordPress.org-compatible release.
* Adds intentional connection, catalog sync, exact product/variation configuration, idempotent quote/order creation, signed webhook processing, status polling, and fail-closed local COA publishing.
