Своя команда ИИ-агентов для управления сайтами на базе WordPress & WooCommerce

---
name: wordpress-wpcraft
description: Manage WordPress site wpcraft.ru content via REST API. Use when: (1) creating or updating posts/pages, (2) adding or listing comments, (3) analyzing categories and tags, (4) searching or filtering content, (5) any WordPress content management task via API for wpcraft.ru. For products and product reviews — use WooCommerce REST API (wc/v3).
---

# WordPress & WooCommerce REST API — wpcraft.ru

Manage WordPress content and WooCommerce products on **wpcraft.ru** via REST API.

## Documentation

- **WordPress REST API:** https://developer.wordpress.org/rest-api/
- **WooCommerce REST API:** https://woocommerce.github.io/woocommerce-rest-api-docs/#introduction

## Auth

Credentials are stored in `~/.openclaw/.env`. Load them before making requests:

```bash
WP_URL=https://wpcraft.ru
WP_USER=<from .env>
WP_APP_PASSWORD=<from .env>  # Application Password (spaces OK, stripped automatically)
```

Use **Application Passwords** (WordPress 5.6+): `Authorization: Basic base64(user:app_password)`


## API Namespaces

| Use case                    | Base URL                          |
|-----------------------------|-----------------------------------|
| Posts, pages, comments, users, media | `${WP_DDPA_URL}/wp-json/wp/v2/` |
| **Products, reviews, categories** | `${WP_DDPA_URL}/wp-json/wc/v3/` |

> ⚠️ **Important:** For anything related to **products** or **product reviews** — always use the **WooCommerce API** (`wc/v3`), not the WP REST API (`wp/v2`).

## Key Endpoints — WordPress API (`wp/v2`)

| Resource    | Endpoint                        |
|------------|----------------------------------|
| Posts      | `/wp/v2/posts`                   |
| Pages      | `/wp/v2/pages`                   |
| Comments   | `/wp/v2/comments`                |
| Categories | `/wp/v2/categories`              |
| Tags       | `/wp/v2/tags`                    |
| Media      | `/wp/v2/media`                   |

## Key Endpoints — WooCommerce API (`wc/v3`)

| Resource              | Endpoint                              |
|-----------------------|---------------------------------------|
| Products              | `/wc/v3/products`                     |
| Product categories    | `/wc/v3/products/categories`          |
| Product tags          | `/wc/v3/products/tags`                |
| Product reviews       | `/wc/v3/products/reviews`             |

### WooCommerce — Common Operations

#### List products
```bash
GET /wc/v3/products?per_page=20&status=publish
GET /wc/v3/products?search=screenshot&per_page=20
GET /wc/v3/products?category=<id>&per_page=100
GET /wc/v3/products?_fields=id,name,slug,permalink,type,status
```

#### Create product
```bash
POST /wc/v3/products
{
  "name": "Product Name",
  "type": "external",          # external = link to third-party tool/app
  "status": "publish",
  "description": "<p>Full HTML description</p>",
  "short_description": "<p>Short summary</p>",
  "external_url": "https://example.com",
  "button_text": "Перейти на сайт",
  "categories": [{"id": 123}],
  "tags": [{"id": 456}]
}
```

#### Update product
```bash
PUT /wc/v3/products/<id>
{ "description": "Updated content" }
```

#### List product reviews
```bash
GET /wc/v3/products/reviews?product=<id>&per_page=20
GET /wc/v3/products/reviews?status=approved
```

#### Create product review
```bash
POST /wc/v3/products/reviews
{
  "product_id": <id>,
  "review": "Текст отзыва",
  "reviewer": "Имя автора",
  "reviewer_email": "email@example.com",
  "rating": 5               # 1–5
}
```

#### Product categories
```bash
GET /wc/v3/products/categories?per_page=100&_fields=id,name,slug,count,parent
POST /wc/v3/products/categories
{ "name": "Screenshots", "slug": "screenshots", "parent": 0 }
```

## Common Operations

See `references/posts.md` — create, update, list, filter posts  
See `references/comments.md` — add, list, moderate comments  
See `references/taxonomy.md` — categories and tags analysis  
See `references/woocommerce.md` — **products, product categories, tags, reviews, attributes** (WooCommerce API)  

## Добавление комментариев на основе поста

Workflow для публикации комментариев от лица Author Bot пользователей по ссылке на пост.
Ссылки на блог начинаются https://ddpa.ru/b/% где % — slug поста. Например: https://ddpa.ru/b/novyy-post/

### Шаг 1 — Получить ID поста из URL

```js
// Из URL вида https://ddpa.ru/b/some-post-slug/
// Запросить по slug:
GET /wp/v2/posts?slug=some-post-slug&_fields=id,title,link
```

Или если URL содержит `?p=12345` — ID уже известен.

### Шаг 2 — Получить список Author Bot пользователей с биографиями

```js
GET /wp/v2/users?roles=author_bot&per_page=100&_fields=id,name,slug,description
```

Поле `description` содержит bio пользователя — его специализацию, интересы, профессиональный background.  
Перед выбором автора **обязательно** проанализировать bio каждого и выбрать того (или тех), чья специализация наиболее релевантна теме поста.

Пример: если пост про безопасность — выбрать пользователя с bio про infosec; если про frontend — того, кто описан как веб-разработчик.  
Комментарий должен отражать экспертизу и точку зрения конкретного персонажа.

### Шаг 3 — Сгенерировать текст комментария

Прочитать содержимое поста:
```js
GET /wp/v2/posts/<id>?_fields=title,content,excerpt
```

Перед написанием комментария чётко определить:
- **Тема поста** — о чём он, какова главная мысль
- **Кто комментирует** — имя, bio, специализация выбранного автора
- **Точка пересечения** — как тема поста касается его профессиональной области

Комментарий должен:
- Писаться **от первого лица**, в голосе конкретного персонажа (его экспертиза, его опыт)
- Содержать **конкретику из его области** — упоминать инструменты, термины, кейсы, характерные для его специализации
- Быть **релевантным теме поста** — реагировать на конкретные тезисы из текста, а не писать абстрактно
- Звучать **естественно** — как комментарий живого читателя-эксперта, не реклама и не резюме статьи
- Быть **умеренной длины** — 2–4 предложения

**Пример логики:** пост про S3-хранилища → выбрать Глеба Алексеева (хостинг/домены) или Романа Волкова (eCommerce) → комментарий от Глеба про опыт работы с конкретным хостингом и сравнение с S3.

### Шаг 4 — Сгенерировать случайную дату комментария

Комментарий должен выглядеть естественно — с рандомной датой и временем.

**Правила:**
- Дата должна быть **не раньше даты публикации поста** (`date` из ответа API)
- Дата должна быть **не позже текущего момента**
- Время — случайное в диапазоне рабочих часов (08:00–23:00), можно в любой часовой зоне
- Если комментариев несколько — у каждого своя независимая случайная дата

Получить дату поста:
```js
GET /wp/v2/posts/<id>?_fields=id,date
// date формат: "2024-11-15T10:30:00"
```

Сгенерировать случайную дату между `post.date` и `now`:
```js
const postDate = new Date(post.date);
const now = new Date();
const randomTs = postDate.getTime() + Math.random() * (now.getTime() - postDate.getTime());
const randomDate = new Date(randomTs);
// Форматировать как: "2024-11-20T14:22:00"
```

### Шаг 5 — Опубликовать комментарий

```js
POST /wp/v2/comments
{
  "post": <post_id>,
  "content": "Текст комментария",
  "author": <user_id>,   // ID из Author Bot списка — комментарий публикуется от его имени
  "date": "<случайная дата в формате ISO 8601, см. Шаг 4>"
}
```

> **Важно:** при указании `author` (ID существующего пользователя) комментарий публикуется от его имени. Поля `author_name` / `author_email` не нужны.  
> Аутентификация должна быть от имени администратора (aiiddqd).  
> Поле `date` задаёт дату комментария — всегда передавай случайную дату согласно Шагу 4.

### Шаг 6 — Проверить результат

```js
GET /wp/v2/comments?post=<post_id>&per_page=5&orderby=date&order=desc
```

Убедиться, что комментарий появился со статусом `approved`.

---

## Scripts

- `scripts/wp_api.mjs` — WPClient class with auth + helper methods (ES module)
- `scripts/wp_analyze.mjs` — analyze categories/tags usage across posts

## Workflow

1. Load `.env` (read `~/.openclaw/.env` or project `.env`)
2. Build auth header
3. Call endpoint with appropriate HTTP method
4. Parse JSON response — check for `code` field in errors

## Error Handling

| HTTP Code | Meaning                        |
|-----------|-------------------------------|
| 401       | Auth failed — check credentials |
| 403       | Permission denied               |
| 404       | Resource not found              |
| 422       | Invalid params                  |

WP errors return JSON: `{"code": "...", "message": "...", "data": {...}}`