=== Facet for WooCommerce ===
Contributors: facetllc
Tags: woocommerce, agents, agentic commerce, agents-txt, facet
Requires at least: 6.4
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.7
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Connect your WooCommerce store to the Facet Terminal for agent commerce: discovery, one-click connect, fast order lookup, and Facet-order email suppression.

== Description ==

Facet for WooCommerce connects your store to the Facet Terminal so AI shopping agents can discover, quote, and buy from you.

* **Agent discovery.** Advertises your Terminal via an `agents.txt` pointer in your site `<head>`, and can optionally serve `/.well-known/agents.txt`, `/.well-known/facet-association.json`, and `/.well-known/ucp` (the UCP-native discovery profile) from your domain, so both Facet agents and UCP-native agents find your Terminal.
* **One-click connect.** Links your store to Facet over the standard WooCommerce `wc-auth` handshake. Facet never receives your admin password; your store approves read/write API access directly.
* **Fast order lookup.** An authenticated REST route lets the Terminal resolve a Facet order to your Woo order id instantly (no full-history scan).
* **Email suppression.** Customer emails are automatically suppressed for orders an agent created through Facet, so shoppers aren't double-notified.

The plugin is compatible with WooCommerce High-Performance Order Storage (HPOS) and legacy order storage.

== External services ==

This plugin connects your store to the Facet Terminal, an external service operated by Facet, LLC, so AI shopping agents can discover, quote, and buy from you. The plugin is inert until you enter a Terminal URL and connect your store: no data leaves your site before that.

What is sent, and when:

* On connect: your store URL and Facet Site ID are sent to the Facet admin at app.facet.llc to begin the standard WooCommerce authorization handshake. WooCommerce core, not this plugin, then issues the scoped API keys directly to Facet.
* On agent order lookup or refund: when the Terminal resolves or refunds an order that an agent placed through Facet, order identifiers and refund amounts are exchanged over an authenticated, signed request. Only Facet orders are involved; ordinary store orders are never sent.
* When you serve discovery from your own domain: your public /.well-known/agents.txt and /.well-known/ucp mirror your Terminal's canonical manifest and UCP profile, each fetched with an unauthenticated GET from the Terminal URL you configured. No store or customer data is sent, and the result is cached. If the Terminal is unreachable, agents.txt falls back to a minimal manifest built from your settings, and /.well-known/ucp returns a 404 rather than a hand-built profile.

The service is operated by Facet, LLC. By connecting your store you agree to the Facet Terms of Service and Privacy Policy:

* Terms of Service: https://facet.llc/legal/terms.html
* Privacy Policy: https://facet.llc/legal/privacy.html

== Third-party libraries ==

This plugin bundles one third-party JavaScript library:

* js-sha3 (version 0.8.0), a keccak-256 / SHA-3 hasher by Chen, Yi-Cyuan, MIT licensed. Bundled at assets/js/vendor/sha3.js and used only in the browser, on the order screen, to hash the ERC-3009 refund digest for a gasless contract-wallet signature. It makes no network calls. Upstream: https://github.com/emn178/js-sha3

== Installation ==

1. Install and activate the plugin (WooCommerce must be active).
2. Go to **WooCommerce → Facet**.
3. Enter your Terminal URL and Facet Site ID (from your Facet onboarding).
4. Click **Connect to Facet** and approve access when your store prompts you.

== Frequently Asked Questions ==

= Does Facet get my admin password? =
No. Connecting uses WooCommerce's built-in `wc-auth` flow: your store issues scoped API keys directly to Facet. The plugin never handles those keys.

= Will my customers still get order emails for agent orders? =
By default no: customer emails are suppressed for orders created through Facet, so shoppers are not double-notified. The one exception is opt-in. When the buyer's agent supplies a contact email on the order, that order's completed-order email (the shipping and completion confirmation) is sent to that address, and nothing else; every other customer email stays suppressed. Facet orders without a contact email keep the full suppression, and normal (non-Facet) orders email as usual. You can still override any of this with the `facet_ffw_suppress_email` filter.

= Does this work with HPOS? =
Yes. The plugin declares HPOS compatibility and uses only HPOS-safe order APIs.

== Changelog ==

= 1.0.7 =
* Gasless refunds for contract-wallet payout treasuries. A CoinbaseSmartWallet payout wallet (a code-bearing treasury) can now approve an agent refund with a single gasless signature, the same way a plain-key wallet already does, instead of broadcasting its own on-chain transfer and paying gas. The signature is verified against the wallet on-chain before anything is relayed; if it cannot be verified, or Facet declines to relay it, the panel falls back to the previous broadcast path. Bundles a keccak-256 hasher (js-sha3, MIT) for the in-browser hashing this needs.

= 1.0.6 =
* Refund panel errors now render as readable text. When the Terminal returns a structured error while previewing or approving a refund, the "Facet Refunds" panel now shows the error message instead of "[object Object]".

= 1.0.5 =
* Merchant refund approval now RELEASES a still-committed Boson escrow. Approving an escrow refund ticket whose funds are still held on-chain (state COMMITTED) previously failed with "approving would cancel this order for nothing", because the panel assumed the buyer had already cancelled. The Terminal signs the seller revoke on approve (gasless, server-side, no merchant wallet), so the panel now approves a releasable ticket and only withholds when the escrow genuinely cannot be released by approving (already redeemed, disputed, or unreadable).

= 1.0.4 =
* Opt-in shipping confirmation. When a buyer's agent supplies a contact email on a Facet order, that order's completed-order email (the shipping and completion confirmation) is now sent to that address, while every other customer email stays suppressed. Facet orders without a contact email keep the full email suppression. The `facet_ffw_suppress_email` filter still overrides the behavior.

= 1.0.3 =
* Adds UCP-native discovery. Your storefront can now serve `/.well-known/ucp`, mirrored from your Terminal's canonical UCP profile, so a UCP-native shopping agent that probes your own domain finds your Terminal's UCP endpoints and payment handlers. Cached like agents.txt; if the Terminal is unreachable the storefront returns a 404 rather than a hand-built profile.

= 1.0.2 =
* Discovery now mirrors your Terminal's canonical agents.txt, so the file served from your domain always matches what Facet advertises (correct KYA issuers, commerce rails, checkout URL, and response signing) and can never drift from it. The minimal manifest built from your settings is now a fallback, used only when the Terminal is unreachable.

= 1.0.1 =
* Adds non-custodial refund handling. A merchant can approve and sign refunds for agent orders from their own wallet, on the order's own chain, directly from the WooCommerce order screen.

= 1.0.0 =
* Initial release: agent discovery, wc-auth connect, order-lookup REST route, and Facet-order email suppression.

== Upgrade Notice ==

= 1.0.7 =
Contract-wallet payout treasuries can now approve agent refunds with a single gasless signature instead of paying their own gas.

= 1.0.6 =
Refund panel errors now show a readable message instead of "[object Object]".

= 1.0.4 =
Buyers can now opt in to a shipping confirmation email on agent orders; all other customer emails stay suppressed.

= 1.0.3 =
Your storefront can now serve /.well-known/ucp, so UCP-native agents discover your Terminal directly from your own domain.

= 1.0.2 =
Your storefront agents.txt now mirrors the Terminal's canonical manifest, so it stays correct automatically.

= 1.0.1 =
Adds merchant-approved, non-custodial refunds for agent orders.

= 1.0.0 =
Initial release.
