=== Flx Commerce ===
Contributors: rickey29
Tags: woocommerce, ai-commerce, machine-readable, agentic-commerce, rest-api
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Requires Plugins: woocommerce
Stable tag: 0.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Exposes machine-readable merchant, product, and commerce capability data from WooCommerce, with real cart, checkout, and Cash-on-Delivery order APIs.

== Description ==

Flx Commerce prepares an existing WooCommerce store to participate in
AI-driven ("agentic") commerce by exposing reliable, machine-readable
information about the merchant, its product catalog, and what the store
can actually do — and by letting an external client drive a **real**
WooCommerce cart, checkout, and order through the store's own existing
setup.

WooCommerce remains the source of truth for every commerce fact this
plugin exposes. Flx Commerce stores no products, carts, checkouts,
orders, or customer data of its own; it reads from and acts through
WooCommerce's own APIs (including its Store API) at the time each request
is made.

= What it does today =

* **Merchant discovery** — a public, read-only REST endpoint describing
  the store (name, URL, description), read live from WordPress's own
  Site Title/Address/Tagline settings.
* **Product discovery** — a public, read-only REST endpoint listing the
  store's catalog, including simple, external, and variable products with
  their variations represented correctly (a variable product is never
  given a single fabricated price). Supports pagination.
* **Commerce capability discovery** — a public REST endpoint reporting,
  truthfully, which of the capabilities below are actually implemented,
  so a client can check before attempting an operation instead of
  assuming.
* **Real WooCommerce cart mutation** — add, view, update, and remove cart
  items via WooCommerce's own Store API; no separate Flx cart exists.
* **Shipping support** — set a billing/shipping address and select a
  shipping rate on the cart, again entirely through WooCommerce's own
  Store API and shipping configuration.
* **Real WooCommerce checkout handoff** — initiate WooCommerce checkout
  for a cart and receive a live preview (payment methods, totals,
  shipping) without placing an order or attempting payment.
* **Real WooCommerce order creation, Cash on Delivery only** — place an
  actual `WC_Order` for a cart. Payment is restricted to Cash on Delivery
  (`cod`) for this release; **no online payment processing of any kind is
  implemented.**
* **UCP discovery/catalog adapter** — exposes the same product catalog
  through the [Universal Commerce Protocol](https://ucp.dev/)'s
  discovery/catalog interface at `/.well-known/ucp` and a
  `catalog.search` REST endpoint. UCP checkout, payment, order creation,
  and `catalog.lookup` are **not** implemented.

= What it deliberately does not do (yet) =

* No online payment gateway integration. Cash on Delivery is the only
  supported order-creation method.
* No support for `grouped` WooCommerce products.
* No UCP checkout/payment/order, no ACP, no MCP shopping surface, and no
  search or ranking beyond returning the full catalog.
* No analytics, tracking, telemetry, or calls to any external service.
  This plugin talks only to your own WordPress/WooCommerce install.
* No new payment infrastructure, no replacement for WooCommerce checkout,
  and no AI chatbot — Flx Commerce is an adapter in front of WooCommerce,
  not a new commerce backend.

= Who this is for =

Store operators who want their existing WooCommerce store to be
discoverable and machine-readable by AI shopping agents and other
commerce clients, while keeping WooCommerce as the single source of
truth for products, pricing, cart, checkout, and orders.

== Features ==

* Public REST API under `/wp-json/flx-commerce/v1/`:
    * `GET /merchant` — merchant identity
    * `GET /products` — product/variant catalog, with pagination
    * `GET /capabilities` — truthful capability flags
    * `GET /cart`, `POST /cart`, `PUT /cart`, `DELETE /cart` — view/add/update/remove cart items
    * `POST /cart/address` — set billing/shipping address
    * `POST /cart/shipping-rate` — select a shipping rate
    * `POST /checkout` — initiate checkout (preview only, no order)
    * `POST /order` — place a real order (Cash on Delivery only)
    * `POST /ucp/catalog/search` — UCP catalog search adapter
* `GET /.well-known/ucp` — the UCP merchant profile document
* Session continuity via WooCommerce's own Store API `Cart-Token`
  mechanism — no cookies or session storage of Flx's own.

== Requirements ==

* WordPress 6.5 or later.
* PHP 7.4 or later.
* [WooCommerce](https://wordpress.org/plugins/woocommerce/), installed
  and active. Flx Commerce does nothing on its own without it.

== Installation ==

1. Ensure WooCommerce is installed and active.
2. Upload the `flx-commerce` folder to `/wp-content/plugins/`, or install
   the plugin ZIP through **Plugins → Add New → Upload Plugin** in
   wp-admin.
3. Activate **Flx Commerce** through the **Plugins** screen.
4. No configuration screen is required. Confirm the REST API responds by
   visiting `/wp-json/flx-commerce/v1/capabilities` on your site.

Activation registers the `/.well-known/ucp` route and flushes rewrite
rules once; no other setup step is needed.

== Usage / API overview ==

All endpoints are under your site's REST API namespace,
`/wp-json/flx-commerce/v1/`. Discovery endpoints (`/merchant`,
`/products`, `/capabilities`, `/ucp/catalog/search`, and
`/.well-known/ucp`) are public and read-only, matching a normal
storefront's own public product/catalog visibility.

Cart, checkout, and order endpoints are also public, matching the same
public/customer-facing model WooCommerce's own Store API uses for
storefront visitors — placing an order still only does what WooCommerce
itself would allow an anonymous customer to do. A first cart mutation
returns a `Cart-Token` response header; send it back as a `Cart-Token`
request header on subsequent calls to keep acting on the same cart.
Order creation additionally validates that `Cart-Token` and rejects any
`payment_method` other than `cod`.

== Frequently Asked Questions ==

= Does this plugin process payments? =

No. `POST /order` can only create an order using Cash on Delivery
(`cod`), which contacts no payment processor and moves no money. No
online payment gateway integration exists in this release.

= Does this replace WooCommerce checkout? =

No. Flx Commerce delegates every cart, checkout, and order operation to
WooCommerce's own Store API and order-creation code. It adds a
machine-readable REST surface in front of WooCommerce; it does not
reimplement or replace any part of WooCommerce.

= Does this plugin store any of my store's data? =

No. Merchant, product, cart, checkout, and order data are all read from
or acted through WooCommerce's own APIs at request time. The only data
this plugin persists is a small internal option tracking its own
installed version, used to manage its `/.well-known/ucp` rewrite rule
safely — no store, product, customer, or order data.

= Does this plugin send data to any external service? =

No. Flx Commerce makes no outbound calls to any third-party or Flx-owned
service. Its REST endpoints only ever talk to your own
WordPress/WooCommerce install (via WordPress's own internal REST
dispatch and, for checkout/order, a loopback HTTP request to your own
site's REST API).

= What is UCP, and is it fully supported? =

UCP (Universal Commerce Protocol) is an open protocol for AI commerce
discovery. This plugin implements only its discovery/catalog interface —
a merchant profile document and a catalog-search endpoint. UCP checkout,
payment, order creation, and product lookup are not implemented.

= Which product types are supported? =

Simple, external, and variable products (including their variations).
Grouped products are not currently supported.

= Is there a settings page? =

No. This release has no configuration UI; behavior is either automatic
(discovery endpoints) or governed by WooCommerce's own store
configuration (shipping, available payment methods, etc.).

== Limitations ==

* Cash on Delivery is the only supported `payment_method` for order
  creation. No other payment gateway can be used through this plugin's
  `/order` endpoint, regardless of what is enabled in WooCommerce.
* `grouped` WooCommerce products are not represented in product
  discovery or cart operations.
* UCP support is limited to discovery/catalog (`/.well-known/ucp` and
  `catalog.search`); UCP checkout, payment, order, and
  `catalog.lookup` are not implemented.
* No other AI-commerce protocol (ACP, MCP as a shopping surface, or
  similar) is implemented.
* No search, filtering, or ranking is performed — `/products` and
  `/ucp/catalog/search` return the store's current catalog as-is.
* There is no admin settings screen in this release.

== Changelog ==

= 0.1.0 =
* First public release. Merchant discovery, product/variant discovery,
  commerce capability discovery, real WooCommerce cart mutation,
  shipping address/rate support, checkout handoff, real order creation
  (Cash on Delivery only), and a UCP discovery/catalog adapter.

== Upgrade Notice ==

= 0.1.0 =
First public release.
