@hostinger/mcp 3.3.0 → 3.3.1

package/skills/headless/steps/04-content-model/wordpress/woocommerce.md

@@ -0,0 +1,153 @@
+# headless — WooCommerce cookbook (headless store on WordPress)
+
+A companion recipe to `SKILL.md` (WordPress content model). Use it whenever the WordPress backend carries
+a **WooCommerce store** (`site.json → woocommerce.enabled: true`) — a brief whose **Suggested backend** is
+`**WordPress + WooCommerce**` (one site: content **and** commerce).
+
+**WooCommerce is not a separate backend.** It is the `woocommerce` plugin on a normal headless WordPress
+install at `/cms` (installed in the provision step). This cookbook is the authoritative home for the store
+data layer: how to **seed and CRUD** products, categories and coupons, and how the **storefront** reads
+the cart, coupons and checkout.
+
+---
+
+## 1 — The one rule: drive the store through the per-site WP MCP
+
+A **custom plugin cannot be installed into a headless `/cms`** from a coding agent (same limit that
+removed `wp-development.md`). So there is **no seed plugin, no WP-CLI, and no REST consumer key in this
+flow.** Instead, the **per-site WP MCP** (the Hostinger AI Assistant — the same JWT session the WordPress
+content push uses, see `SKILL.md` Step 1) exposes **native WooCommerce abilities**. Seed and manage the
+catalog through them, exactly as posts/pages are created.
+
+Relevant abilities (names from `hostinger-ai-discover-abilities`; call `get-ability-info` for each schema
+before use — they mirror the WooCommerce REST v3 shapes):
+
+| Area | Abilities |
+|---|---|
+| Products | `wc-products-search` · `wc-products-get` · `wc-products-create` · `wc-products-update` · `wc-products-delete` |
+| Categories / tags / brands | `wc-product-categories-{list,create,update,delete}` · `wc-product-tags-*` · `wc-product-brands-*` |
+| Coupons | `wc-coupons-{search,get,create,update,delete,batch}` |
+| Orders | `wc-orders-{search,get,create,update,delete}` |
+| Reports | `wc-reports-{sales,orders-totals,products-totals,coupons-totals,…}` |
+| Media | `media-upload-from-url` (product images — WordPress keeps its own copy) |
+
+All run as the install's admin **inside the MCP session** — no consumer keys, no Basic Auth. This is
+proven: a `wc-products-create` call makes a product that immediately appears on the public Store API.
+
+---
+
+## 2 — The storefront reads the public Store API
+
+The **frontend** never touches the per-site MCP or any key. It reads the **public WooCommerce Store API**
+at `site.json → urls.store_api` (`/cms/wp-json/wc/store/v1`) — public, open CORS, no auth for reads.
+Pretty permalinks are on by default on a headless install, so the Store API resolves immediately.
+
+| Store API call | Use |
+|---|---|
+| `GET /products?per_page=100` · `GET /products/<id>` · `?slug=<slug>` | catalog + product pages |
+| `GET /products/categories` | category nav |
+| `GET /cart` | current cart (seeds the `Cart-Token`) |
+| `POST /cart/add-item` `{ id, quantity }` · `/cart/update-item` `{ key, quantity }` · `/cart/remove-item` `{ key }` | cart mutations |
+| `POST /cart/apply-coupon` `{ code }` · `/cart/remove-coupon` `{ code }` | coupons on the cart |
+| `POST /checkout` `{ billing_address, shipping_address, payment_method }` | place an order |
+
+**Store API auth for writes** (cart/checkout): send the **`Nonce`** header (read it from the `Nonce` /
+`X-WC-Store-API-Nonce` response header of a prior Store API GET and echo it back) **and** the
+**`Cart-Token`** header (a JWT the Store API returns on the first cart response — resend it on every
+cart call so a headless client keeps one cart; persist it in `localStorage`). Reads need neither.
+
+**Pricing / minor units.** The Store API returns **integer-string** prices in minor units plus the
+divisor: `prices.price` (e.g. `"1999"`) with `prices.currency_minor_unit` (e.g. `2`) and
+`prices.currency_code`. Display value = `Number(price) / 10 ** currency_minor_unit`. **Pagination:**
+`?page=&per_page=` (max 100), with `X-WP-Total` / `X-WP-TotalPages` headers.
+
+---
+
+## 3 — Seeding the catalog (content-model push)
+
+Run after provision installed + activated WooCommerce (`site.json → woocommerce.enabled: true`), inside
+the authenticated per-site WP MCP session (`SKILL.md` Step 1). Seed from the prepared catalog in
+`content-model.md`. **Idempotent by SKU** (products) and **code** (coupons) — list/search first, create
+only if absent, so a re-run never duplicates.
+
+1. **Product categories** — for each category: `wc-product-categories-list` (match by `slug`/`name`,
+   reuse the id) else `wc-product-categories-create { name, slug }`. Keep `name → id`.
+2. **Products** — for each product: `wc-products-search { sku: "<sku>" }`; a hit → reuse its id; empty →
+   `wc-products-create`:
+   ```json
+   { "name": "...", "type": "simple", "sku": "<unique>", "regular_price": "39.99",
+     "description": "...", "short_description": "...", "status": "publish",
+     "categories": [ { "id": <catId> } ] }
+   ```
+   - `regular_price` is a **decimal string in major units** (`"39.99"`) on the ability side — the Store
+     API re-exposes it as minor units to the storefront.
+   - **Variable products:** create the parent (`type: "variable"`) with its attributes, then the
+     variations (via the product update / variations ability that discovery lists).
+3. **Product images** — `media-upload-from-url { url, filename, alt_text, title }` (WordPress downloads
+   and stores its own copy; raster, HTTPS, direct file URL — source like the parent `SKILL.md` Unsplash
+   flow). Attach the returned media id to the product (`wc-products-update { id, images: [ { id } ] }`).
+   Idempotency: skip when the product already has images.
+4. **Coupons** — for each coupon: `wc-coupons-search { code }`; empty → `wc-coupons-create`:
+   ```json
+   { "code": "WELCOME10", "discount_type": "percent", "amount": "10" }
+   ```
+   (`discount_type`: `percent` | `fixed_cart` | `fixed_product`.)
+
+Record the SKU → id map, category ids and coupon codes into `content-model.md` under
+`## Created in WooCommerce` so the frontend and any re-run resolve references directly.
+
+**Verify over the public Store API (no auth):**
+- `GET {store_api}/products?per_page=100` → count matches the plan; each has `prices` (minor units +
+  `currency_minor_unit`) and, where seeded, an image.
+- `GET {store_api}/products/categories` → every planned category present.
+- Coupon: `wc-coupons-search { code }` returns it, or apply it to a throwaway cart and see the total drop.
+
+---
+
+## 4 — Checkout is owner-completed (the one gate)
+
+A fresh WooCommerce install has **no payment gateway and no shipping zone enabled**, and **neither is
+reachable from the headless tooling** — there is no payment/shipping MCP ability, and `wp-settings-update`
+only writes standard WordPress settings (it ignores `woocommerce_*` options). So:
+
+- **The catalog, product pages, client-side cart and coupon application all work headlessly.**
+- **Checkout (`POST /checkout`) does not work until the owner enables a payment method + a shipping zone
+  in wp-admin** (WooCommerce → Settings → Payments / Shipping; reach it via the one-click login in Step 9).
+  Cash on Delivery is the zero-config choice once enabled.
+- Treat this exactly like the Hostinger Ecommerce `payment_enabled: false` gate: record
+  `woocommerce.payment_enabled: false`, tell the user in one line that checkout needs that one setup step,
+  and **never block the build on it**. The frontend renders a graceful disabled-checkout state and does not
+  call `/checkout` while `payment_enabled` is `false`. Flip it to `true` only after the owner confirms a
+  gateway is live. **Never ask the user for payment credentials.**
+
+Store **currency** and **address** (`woocommerce_*` options) likewise aren't settable headlessly — they
+follow the install default; the owner changes them in wp-admin if needed.
+
+---
+
+## 5 — REST API v3 (optional, owner-only — not used by this flow)
+
+WooCommerce also exposes the authenticated **REST API v3** at `site.json → urls.wc_rest_api`
+(`/cms/wp-json/wc/v3`) for external/server-side integrations. **This build never uses it** — seeding goes
+through the per-site MCP and the storefront uses the public Store API. Document it for the owner only:
+
+- **Auth:** `Authorization: Basic base64("<consumer_key>:<consumer_secret>")`, **HTTPS only**, server-side
+  only — **never ship a key to the browser.**
+- **Keys:** the owner generates a key pair in **wp-admin → WooCommerce → Settings → Advanced → REST API**
+  (the agent cannot mint one headlessly). Store it in the owner's own environment, not in `site.json` or
+  the repo.
+- **Endpoints** (same shapes as the abilities above): `GET/POST/PUT/DELETE /products`, `/products/<id>/variations`,
+  `/products/categories`, `/coupons`, `/orders`. Idempotency via `?sku=` / `?code=`. Pagination via
+  `?page=&per_page=` + `X-WP-Total`.
+
+---
+
+## 6 — Idempotency & verification checklist
+
+- **Idempotency keys:** products → **SKU** (`wc-products-search { sku }`); coupons → **code**
+  (`wc-coupons-search { code }`); categories → **slug/name**; images → skip when the product already has
+  `images`.
+- **Verify over the public Store API** (no auth) — products count + prices + categories, and a coupon via
+  a cart apply. Record the id/SKU map into `content-model.md`.
+- **Checkout** is verified only when `payment_enabled` is `true`; while `false`, confirming the catalog +
+  cart over the Store API is the whole job.

package/skills/headless/steps/05-design/SKILL.md

@@ -13,6 +13,15 @@ not a conversation: the frontend step implements `design.md`, not the chat.
 user gave. **Out:** `~/.hostinger/<domain>/design.md` and the logo files in
 `~/.hostinger/<domain>/brand/`.
 
+> ## ⚠️ Build mode: "Bring your own frontend"? This step defers to the user
+> Read `brief.md` → **Build mode** first. When it is **Bring your own frontend**, the user drives the
+> design — **do not generate three directions or write a prescriptive `design.md` over their project.**
+> The frontend already exists (or the user vibe-codes it with you); your job is to follow *their*
+> direction, not impose one. Skip Steps 1–7 below: either write nothing, or capture only what the user
+> explicitly asks for (a short note of their stated colours/vibe) so the frontend step has it. The logo
+> and token work here apply only when **Build mode is "Agent designs and builds"**. (This mirrors the
+> frontend step's existing "existing app the user brought" handling, now generalised to any backend.)
+
 This is **prepare work**: it runs while provision settles (see *Background provision & the instance
 barrier* in the top-level `SKILL.md`). Nothing here calls the Hostinger connector or the backend.
 

package/skills/headless/steps/06-frontend/SKILL.md

@@ -11,6 +11,18 @@ is where it becomes real code. There's no per-framework recipe — use good judg
 as the contract, and ask only for the clarifications you genuinely need. **Out:** source in the site
 workspace `~/.hostinger/<domain>/src/`.
 
+> ## ⚠️ Build mode: "Bring your own frontend"? Read this first (any backend)
+> Read `brief.md` → **Build mode**. When it is **Bring your own frontend**, the user already has a
+> frontend (the project in the folder the command was run in) and this step **wires it to the backend
+> from `site.json` — it does not scaffold a new project and there is usually no `design.md` to
+> implement** (the design step deferred to the user). **Use their project as the source**: copy or
+> point `~/.hostinger/<domain>/src/` at it, keep its framework and UI, and collaborate on changes at
+> the user's direction (vibe-code with them). Your job is to connect it to the live backend (WordPress
+> `wp/v2` reads, the WooCommerce/Ecommerce Store API, env/keys) and make it deployable (set
+> `engines.node` to `22`, remove any `.htaccess`), then hand off to deploy. This generalises the Webapp
+> "existing app" case below to WordPress and Ecommerce too. When **Build mode is "Agent designs and
+> builds"**, ignore this box and proceed normally (scaffold + implement `design.md`).
+
 > ## ⚠️ Webapp backend? Read this first
 > A `webapp` brief has **no CMS/store and no `content-model.md`** — the app owns its own data (its own
 > API, or the MySQL database recorded in `site.json → database`). It comes in two shapes, decided back in
@@ -27,7 +39,7 @@ workspace `~/.hostinger/<domain>/src/`.
 >   there is still **no `content-model.md`** to bind against.
 >
 > Framework choice (Step 1), the build, and hand-off (Step 4) apply to both. The per-backend bullets in
-> Step 3 are **WordPress/Ecommerce only** — for a webapp follow the Webapp bullet there.
+> Step 3 are **WordPress / WooCommerce / Ecommerce only** — for a webapp follow the Webapp bullet there.
 
 ## Step 1 — Pick the framework (guess → default → confirm)
 
@@ -36,6 +48,7 @@ it, and the backend constraint:
 
 - **Ecommerce → SSR required** (carts/search need per-request rendering). Any SSR framework works —
   Next.js is the default, not a requirement (Express, Nuxt, SvelteKit, etc. are all fine).
+- **WordPress + WooCommerce → SSR required** (same reason — cart/checkout need per-request rendering).
 - **WordPress → SSG (Astro)** when the brief says SSG, otherwise **SSR (Next.js default)**.
 - **Webapp → the app's own stack.** An **existing app** keeps its current framework (don't impose one); a
   **new app** uses whatever fits the brief (SSR or SPA). Either way it deploys as a Node.js app (Step 8) —
@@ -87,7 +100,23 @@ Read the backend from `site.json`:
 
 - **WordPress** → `urls.rest_api` (`wp/v2`), public read. Content is in the posts/pages/categories/media
   the content-model push created; nav/plan come from `content-model.md`. Map each item's **SEO** from its
-  `yoast_head_json` into the page `<head>` (title, description, Open Graph, JSON-LD schema).
+  `yoast_head_json` into the page `<head>` (title, description, Open Graph, JSON-LD schema) — Yoast is
+  installed by default at provision (`site.json → seo.enabled: true`). If `seo.enabled` is `false`
+  (Yoast absent), fall back to generating per-page title/description/OG tags from each item's content.
+- **WordPress + WooCommerce** (`site.json → woocommerce.enabled: true`) → the WordPress bullet above **plus**
+  the store. Read the catalog over the **public WooCommerce Store API** (`site.json → urls.store_api`,
+  `/cms/wp-json/wc/store/v1`, no auth, open CORS): `GET /products` (prices are **integer minor units** on
+  `prices.price` with `prices.currency_minor_unit` — divide to display), `GET /products/categories`. Cart,
+  coupons and checkout are **client-side** against the Store API with the `Nonce` + `Cart-Token` headers
+  (`GET /cart`, `POST /cart/add-item`, `/cart/apply-coupon`, `POST /checkout`) — see
+  `../04-content-model/wordpress/woocommerce.md`. **Never embed a consumer key client-side**; the
+  storefront is fully public. Blog/pages on the same site still come from `urls.rest_api` (`wp/v2`) + Yoast.
+  - **Honour `site.json → woocommerce.payment_enabled`.** It is `false` until the owner enables a payment
+    gateway + shipping in wp-admin (that config isn't reachable headlessly — see the provision note). While
+    `false`, build the full catalog, product pages and the client-side cart as normal, but render a
+    graceful disabled-checkout state (e.g. a disabled "Checkout" with "Checkout isn't set up yet"), **don't
+    call `/checkout`**, and don't treat it as a build error. When `true`, wire checkout (`payment_method`
+    `"cod"` works out of the box).
 - **Ecommerce** → the **public Hostinger Storefront Core V2 API** (`https://api-ecommerce.hostinger.com/v2`,
   no auth, open CORS), keyed on the **custom sales channel** (`site.json → ecommerce.sales_channel.id`):
   `GET /channels/<scha_*>/products` (prices are **minor units** on variants), `POST /channels/<scha_*>/checkout`

package/skills/headless/steps/07-validate/SKILL.md

@@ -20,7 +20,7 @@ description: "Step 7 (validate) of the Hostinger Headless flow. OPTIONAL quick g
 `hosting_websites_list-setups { "domain": "<domain>" }`, exact-match the row → `completed`. Anything
 else → not ready; return to the instance barrier, don't deploy.
 
-## 2 — Backend API status (WordPress or Ecommerce, always, quick)
+## 2 — Backend API status (WordPress / WooCommerce / Ecommerce, always, quick)
 
 Hit the live API from `site.json` and confirm it answers **with the content the push created** — a 200
 with an empty catalog means the push didn't land:
@@ -28,6 +28,9 @@ with an empty catalog means the push didn't land:
 - **WordPress:** `GET {urls.rest_api}/posts?per_page=1` → 200 JSON array; check `X-WP-Total` against the
   planned post count, and `GET {urls.rest_api}/media?per_page=1` → `X-WP-Total` matches the planned
   image count (more = duplicates).
+- **WordPress + WooCommerce** (`site.json → woocommerce.enabled`): the WordPress check above **plus**
+  `GET {urls.store_api}/products?per_page=100` → 200 with the seeded products and `prices` (minor units);
+  count matches the plan. Don't test checkout while `woocommerce.payment_enabled` is `false`.
 - **Ecommerce:** query `urls.storefront_api` for the sales channel → 200 with the seeded products and
   prices *(confirm against the store)*.
 

package/skills/headless/steps/08-deploy/SKILL.md

@@ -116,9 +116,15 @@ hangs, `hosting_nodejs_restart-application { username, domain }` recovers the se
 | SSR is live *(server frameworks)* | response headers | `x-powered-by` present, `cache-control: no-store` |
 | Static serves *(static frameworks)* | `GET https://<domain>/` | 200 HTML with real home content |
 | Key routes | a couple of planned routes + one deep route | 200, real content |
-| **Backend survived** *(WordPress only)* | `GET https://<domain>/cms/wp-json/wp/v2/posts?per_page=1` | 200 |
-
-> **Only WordPress has a `/cms` on the domain**, so the *Backend survived* check is WordPress-only.
+| **Backend survived** *(WordPress / WooCommerce)* | `GET https://<domain>/cms/wp-json/wp/v2/posts?per_page=1` | 200 |
+
+> **Only WordPress (including WordPress + WooCommerce) has a `/cms` on the domain**, so the *Backend
+> survived* check is WordPress-only.
+> - **WordPress + WooCommerce:** also confirm the store survived the deploy —
+>   `GET https://<domain>/cms/wp-json/wc/store/v1/products?per_page=1` → 200. There is nothing external to
+>   link (no sales-channel step — that's Ecommerce only). **Checkout** stays owner-completed: when
+>   `site.json → woocommerce.payment_enabled` is `false`, don't test `/checkout`; a catalog that serves 200
+>   is a passing, complete deploy.
 > - **Ecommerce:** the backend is the **Hostinger Ecommerce store**, read over the external Storefront API
 >   (`api-ecommerce.hostinger.com`) — nothing a deploy touches lives on this domain. There is no `/cms`;
 >   confirm the storefront still fetches products as a frontend check if you like. **Only check that
@@ -153,6 +159,8 @@ No secrets in `deploy.json`. The `urls.cms` field and the `backend_preserved` ch
 **WordPress-only** — adjust the record to the backend:
 
 - **WordPress:** keep `urls.cms` and `checks.backend_preserved` as shown.
+- **WordPress + WooCommerce:** keep `urls.cms` + `checks.backend_preserved` (it *is* WordPress), and add
+  `urls.store_api` from `site.json`; no external link step.
 - **Ecommerce:** omit `urls.cms`/`backend_preserved`; record the store URLs instead (`urls.storefront_api`,
   `urls.store_admin` from `site.json`) and link the custom sales channel to the live domain —
   `ecommerce_sales-channels_update { store_id, sales_channel_id, url }` (see the ecommerce provision step).

package/skills/headless/steps/09-done/SKILL.md

@@ -17,8 +17,9 @@ already checked this — this is a quick re-confirm, not a full re-run):
 - **Main site:** `GET https://<domain>/` → 200 (Next.js SSR: `x-powered-by: Next.js`; Astro SSG: static
   HTML with real content).
 - **WordPress admin:** `GET {urls.wp_admin}` → reachable (a login page, 200/302), not 404.
-- **Backend API:** `GET {urls.rest_api}/posts?per_page=1` → 200 (WordPress); or the storefront API for
-  the sales channel → 200 (Ecommerce).
+- **Backend API:** `GET {urls.rest_api}/posts?per_page=1` → 200 (WordPress); for a **WooCommerce** store
+  (`site.json → woocommerce.enabled`) also `GET {urls.store_api}/products?per_page=1` → 200; or the
+  storefront API for the sales channel → 200 (Ecommerce).
 
 If a check fails, say so in the outcome paragraph and don't claim the site is live.
 
@@ -61,8 +62,13 @@ Write it in this order:
      auto-login redirect URL** — `wordpress_login_create-links { username, software: <site.json
      wordpress.install_id> }` returns a temporary link that logs the user straight into wp-admin. Give
      that URL as the admin link (it lands on `/cms/wp-admin`), so the user never needs a password. Also
-     note the plain `urls.wp_admin` as a fallback. **Never print or store a password.** For an
-     Ecommerce store, link the store admin from `urls.store_admin` instead.
+     note the plain `urls.wp_admin` as a fallback. **Never print or store a password.** For a
+     **WordPress + WooCommerce** store, this *same* wp-admin login is the store admin (wp-admin →
+     WooCommerce → Products/Orders) — do **not** use the Ecommerce `store_admin` path. **Call out the one
+     setup step under *Gaps / follow-ups*:** when `site.json → woocommerce.payment_enabled` is `false`,
+     the owner must enable a payment method + a shipping zone in WooCommerce → Settings before checkout
+     works (the catalog and cart already work). For a Hostinger **Ecommerce** store, link the store admin
+     from `urls.store_admin` instead.
    - **hPanel site dashboard:** `https://hpanel.hostinger.com/websites/<domain>` (the headless website
      is installed by now).
    - **Onboarding (resume):** `https://hpanel.hostinger.com/headless-onboarding/<order_id>/<username>/`