# 08 — WordPress Connector: Missing v0.4.0 Source and Required Interfaces

**Status:** connector development is **blocked** until the correct source is located.

Neither plugin was modified:
- `C:\wamp64\www\nh\wp-content\plugins\vmwebs-commerce` (v0.3.0) is still untouched and read-only.
- The v0.4.0 build was not found on this machine.

## 1. What is missing

| Item | Evidence | Location |
|---|---|---|
| `vmwebs-commerce` **v0.4.0**, the build that actually calls the POS | The NH POS database copy has audit rows with user agent `VMWebs-Commerce/0.4.0`. Storefront connections exist for `http://localhost/NHweb`, `http://localhost/NHweb/` (name "nhdream.ca") and test sites | **Unknown.** Not under `C:\wamp64\www` (there is no `NHweb` directory). Possibly in another workspace, on another machine, or only on the NH Bitbucket |
| v0.3.0 (on disk) | `vmwebs-commerce.php`, `VMWC_VERSION` 0.3.0, 3 commits (Phase 0 to 2). No outbound HTTP, no POS settings | `C:\wamp64\www\nh\wp-content\plugins\vmwebs-commerce` |

**To locate it**, ask the NH developer or check NH Bitbucket for a `vmwebs-commerce` repository or branch tagged 0.4.x. Also search other drives for `vmwebs-commerce.php` with `Version: 0.4`.

**Do not copy** anything from NH's production WordPress. `backend/docs/security/WORDPRESS_PRODUCTION_INVESTIGATION.md` records a suspected malicious plugin (`lucid-relay-jet`) there. Use only version-controlled source.

## 2. POS-side interface the connector must use

This already exists in the TechTitans backend; see `04` for the full table.

**Base URL** (local dev): `http://localhost:8010/api/v1`

**Authentication:**
- `Authorization: Bearer {connectionUuid}.{secret}`.
- The token is issued per connection by an admin: `POST storefront/connections/{id}/credentials`, permission `storefront_connections.manage`.
- The raw token is shown **once**. Only its hash is stored.
- Tenant and location come from the connection itself. A client-supplied `tenant_id` is rejected.

| Concern | Endpoint(s) | Notes |
|---|---|---|
| Identity / health | `GET storefront/me` | Returns 401 for a bad token and 403 for a disabled connection |
| Catalogue | `GET storefront/catalogues`, `…/{c}`, `…/{c}/categories`, `…/{c}/products?per_page≤50&page`, `…/{c}/products/{p}` | Product and variant UUIDs are the sync keys. Prices are in minor units. `availability{stock_status,purchasable}` |
| Images | Product payload `image` + `gallery[]` | **Signed URLs expire in 30 minutes.** The connector must download them into the Media Library, keyed by media UUID, and not hotlink |
| Quote | `POST storefront/checkout/quote`, `GET storefront/checkout/quotes/{q}` | Server-authoritative totals. Headers `X-Request-Id`, `X-Guest-Token` |
| Order | `POST storefront/checkout/orders` | Header `X-Idempotency-Key`. A `requote` response means prices or stock changed |
| Payment | `POST storefront/checkout/payment-options`, `/payments`, `/payments/confirm` | Hosted tokenization only (Bambora Custom Checkout / Moneris HT). Card data never touches WordPress or the POS |
| Gateway webhook relay | `POST storefront/payments/webhook/{provider}` | WordPress forwards the raw, signed gateway payload |
| Status / tracking / pay links | `GET storefront/checkout/orders/{o}/status`, public `track-links/{token}`, `pay-links/{token}` | — |

## 3. Interfaces still needed for TechTitans (POS side, to build later)

| Need | Proposed interface | Why |
|---|---|---|
| Delta catalogue sync | `?updated_since=ISO8601` plus `ETag` on catalogue and product endpoints | Avoid full re-sync |
| Push notifications to WordPress | Outbox table plus signed outbound webhook (`product.updated`, `stock.changed`, `price.changed`, `order.status_changed`) with HMAC header and retries | The POS currently never calls WordPress |
| Stock quantity exposure | Per-connection policy: `status_only` / `quantity` / `low_stock_threshold` | High-value devices need "only N left" accuracy |
| Checkout reservations | Reserve at order creation, release on expiry or payment failure (Inventory Increment 1.7) | Prevent overselling single-unit used devices |
| Condition-aware listings | Variant attributes `condition`/`grade`, or unit-level listings with per-unit photos (Increment 1.2) | Used and refurbished devices |
| Integer quantities | Reject decimals for serialized items (`StorefrontCheckoutQuoteRequest.php:35` allows `numeric`) | Serialized goods |
| Customer accounts | `storefront/customers/*` (sign-in, order history) | Today the POS only find-or-creates a customer inside an order |
| Token lifecycle | Optional expiry plus a rotation grace window | Today tokens never expire and rotation revokes them immediately |

## 4. Connector-side responsibilities (to build once the source is located)

- Secure storage of the bearer token, reusing the plugin's libsodium `Encryption` helper.
- A scheduled delta sync (WP-Cron or real cron) for catalogue, categories, prices and images.
- A webhook receiver route (`register_rest_route`) that verifies the HMAC.
- Checkout UI: quote, order, hosted payment fields, then confirm.
- Order status and tracking pages.
- Logging with redaction (the plugin already has `Logging/Redactor`).

## 5. Decision needed

Before connector development starts, decide between:
- **(a)** recovering v0.4.0 and forking it into a TechTitans repository, or
- **(b)** building a TechTitans connector, possibly on WooCommerce.

In either case, it should be its own repository and never point at NH's WordPress.