# WooCommerce Bridge Contract

The storefront's `AI Web Command Woo Bridge` is the billing authority integration. It is installed only on `aiwebcommand.com`; client websites use the separate Site Agent plugin.

## Shared configuration

The storefront bridge's **App URL** must point to the SaaS app and its **Shared secret** must match `WOO_SSO_SHARED_SECRET` in the SaaS environment. Set `WOO_SSO_START_URL` to the storefront route `/aiwebcommand-sign-in/`.

## Subscription sync

The bridge sends `POST /api/integrations/woo/subscription` with `X-AIWebCommand-Signature`: a base64 HMAC-SHA256 of the exact JSON body. The request includes Woo customer and subscription IDs, plan code, normalized status, interval, period dates, and an ISO `issuedAt` timestamp. SaaS requests are accepted only when the HMAC is valid and the timestamp is fresh.

Plan codes are fixed:

- `solo-1`: 1 site
- `growth-10`: 10 sites
- `agency-30`: 30 sites

## Customer sign-in

`/aiwebcommand-sign-in/` requires the normal WordPress/WooCommerce login. It creates a short-lived payload and submits it to `/api/auth/woo/exchange`; the SaaS creates its own session cookie after validating the HMAC and single-use nonce. The SaaS never receives a WooCommerce password.