# Abilities API

HelloPack Client registers abilities with the WordPress 6.9+ Abilities API, allowing AI agents and other plugins to discover and execute package manager actions programmatically.

**Requirement:** WordPress 6.9 or later. On older versions nothing is registered and no errors occur.

## Category

All abilities are grouped under the `hellopack` category.

## Available Abilities

### hellopack/list-plugins

List all purchased plugins with their installation and update status.

**Input:** none

**Output:**

```json
{
  "items": [
    {
      "id": 12345,
      "slug": "elementor-pro",
      "name": "Elementor Pro",
      "description": "...",
      "author": "Elementor",
      "version": "3.25.0",
      "thumbnail": "https://...",
      "hasUpdate": true,
      "status": "active",
      "file": "elementor-pro/elementor-pro.php"
    }
  ],
  "stats": {
    "total": 42,
    "active": 10,
    "installed": 15,
    "updates": 3
  }
}
```

**Status values:** `active` (installed and activated), `installed` (installed but inactive), `available` (not yet installed)

### hellopack/list-themes

List all purchased themes with their installation and update status.

**Input:** none

**Output:** Same structure as `list-plugins`, with `stylesheet` instead of `file`.

### hellopack/list-modules

List all registered HelloPack license modules and their state.

**Input:** none

**Output:**

```json
{
  "modules": [
    {
      "id": "acf-pro",
      "name": "ACF Pro",
      "description": "Advanced Custom Fields Pro license management",
      "category": "plugin",
      "enabled": true,
      "active": true
    }
  ]
}
```

**Field meanings:**
- `enabled` — The module is turned on in settings
- `active` — The module is actually running (target plugin/theme is active and module has API access)

### hellopack/connection-status

Get the current license connection status.

**Input:** none

**Output:**

```json
{
  "status": "active",
  "domain": "example.com"
}
```

**Status values:** `active` or `inactive`

### hellopack/check-updates

List plugins and themes that have a newer version available.

**Input:** none

**Output:**

```json
{
  "plugins": [
    {
      "id": 12345,
      "slug": "elementor-pro",
      "name": "Elementor Pro",
      "version": "3.25.0",
      "hasUpdate": true,
      "status": "active",
      "file": "elementor-pro/elementor-pro.php"
    }
  ],
  "themes": []
}
```

### hellopack/toggle-module

Enable or disable a HelloPack license module.

**Input:**

```json
{
  "module_id": "acf-pro",
  "enabled": false
}
```

**Output:**

```json
{
  "message": "Module disabled.",
  "is_active": false
}
```

## Annotations

| Ability | readonly | destructive | idempotent |
|---------|----------|-------------|------------|
| `hellopack/list-plugins` | yes | no | yes |
| `hellopack/list-themes` | yes | no | yes |
| `hellopack/list-modules` | yes | no | yes |
| `hellopack/connection-status` | yes | no | yes |
| `hellopack/check-updates` | yes | no | yes |
| `hellopack/toggle-module` | no | yes | yes |

## Permissions

All abilities require the `manage_options` capability.

## REST API Access

All abilities are exposed via the WordPress Abilities REST endpoint:

```
GET  /wp-json/wp-abilities/v1/abilities          # List all abilities
POST /wp-json/wp-abilities/v1/abilities/{name}    # Execute an ability
```

**Authentication:** Standard WordPress REST authentication (cookie + nonce, or application password).

**Examples with curl:**

```bash
# List all registered abilities
curl -s "https://example.com/wp-json/wp-abilities/v1/abilities" \
  -H "Authorization: Basic <app-password>"

# Check connection status
curl -s -X POST "https://example.com/wp-json/wp-abilities/v1/abilities/hellopack%2Fconnection-status" \
  -H "Authorization: Basic <app-password>"

# List plugins
curl -s -X POST "https://example.com/wp-json/wp-abilities/v1/abilities/hellopack%2Flist-plugins" \
  -H "Authorization: Basic <app-password>"

# Toggle a module
curl -s -X POST "https://example.com/wp-json/wp-abilities/v1/abilities/hellopack%2Ftoggle-module" \
  -H "Authorization: Basic <app-password>" \
  -H "Content-Type: application/json" \
  -d '{"module_id": "acf-pro", "enabled": false}'
```

## MCP Integration

The WordPress MCP Adapter (WP 6.9.1+) automatically exposes registered abilities as MCP tools. AI agents connecting via MCP can discover and call HelloPack abilities without any additional configuration.

## Docker Testing

```bash
# Verify abilities are registered (requires WP 6.9+)
docker compose -f docker/docker-compose.yml exec wordpress \
  wp --allow-root rest get /wp-abilities/v1/abilities

# Execute an ability via WP-CLI
docker compose -f docker/docker-compose.yml exec wordpress \
  wp --allow-root rest post /wp-abilities/v1/abilities/hellopack%2Fconnection-status
```
