Wake-up On LAN (WOL) API

SKILL.md

---
name: wol-api
description: "Use this skill ONLY when the user explicitly refers to WOL / Wake-up On LAN (the Dutch LAN party at wollan.nl) and wants to use its API: the WOL catering (menu, ordering food/drinks, order history, catering balance) or WOL event registration (are registrations open, register/unregister, registration and payment status, choosing a seat). Do not use for generic food ordering, balances or registrations that are not about WOL."
metadata: {"openclaw": {"requires": {"bins": ["python3"]}, "primaryEnv": "WOL_API_TOKEN", "envVars": [{"name": "WOL_API_TOKEN", "required": false}, {"name": "WOL_BASE_URL", "required": false}], "emoji": "⛺️", "os": ["darwin", "linux"]}}
---

# WOL API

All API access goes through the bundled script. It resolves credentials, pins the
base URL, formats money and dates, maps errors to actions, and makes you confirm
before changing anything. **Do not call the API with curl or another tool. Do not
build requests yourself.**

```bash
python3 {baseDir}/scripts/wol.py <command> [options]
```

`{baseDir}` is this skill's directory, the folder containing this SKILL.md.

## Credentials

The script finds the token by itself, so never handle it yourself.

- Never echo, print, cat, log or `export` the token, and never put it in a command line.
- Never ask the user to paste the token into the chat. If they paste one anyway, don't repeat it. Tell them to revoke it at https://wollan.nl/user/api-tokens and create a new one.
- To check the setup, run `auth`. It shows where the token comes from (hidden) and verifies it against the API.
- If no token is configured (exit code 2), ask the user to create a token at https://wollan.nl/user/api-tokens and run the command below **themselves** in a terminal. It prompts for the token with hidden input and stores it in `~/.config/wol/token` (mode 600). They can also set `WOL_API_TOKEN` in their environment instead.
  ```bash
  python3 {baseDir}/scripts/wol.py set-token
  ```
- The base URL is always https://wollan.nl. `WOL_BASE_URL` may only point at wollan.nl or localhost. The script refuses anything else, and you must not work around that.

## Commands

| User intent                                   | Command                                     |
|-----------------------------------------------|---------------------------------------------|
| Check the credential setup                    | `auth`                                      |
| What's on the menu / is X in stock            | `menu`                                      |
| Order food/drinks                             | `order <productId>[:<qty>] ...` (preview)    |
| Catering balance / how much do I owe          | `orders`                                    |
| Order history / is my order ready             | `orders --details [--page N] [--limit N]`   |
| Are WOL registrations open                    | `open`                                      |
| List all events                               | `events`                                    |
| Event details (date, seats, seat selection)   | `event [--event ID]`                        |
| Which seats are free                          | `seats [--event ID]`                        |
| Am I registered / have I paid                 | `registration [--event ID]`                 |
| Register for the next WOL                     | `register [--event ID]` (preview)           |
| Cancel my registration                        | `unregister [--event ID] [--reason TEXT]` (preview) |
| Choose/change my seat                         | `seat --number <seatNumber> [--event ID]` (preview) |

- `--event` defaults to the active event, so you rarely need it.
- Add `--json` before the command (`wol.py --json orders`) only if you need fields the text output lacks.
- Quantity defaults to 1. Map product names to IDs with `menu`, reusing its output from earlier in the conversation when you can.

## State-changing commands: preview, confirm, then execute

`order`, `register`, `unregister` and `seat` **only preview** by default.

1. Run the command without `--yes`. The script validates everything (stock, open registrations, seat availability) and prints a preview with the exact command to run next.
2. Show the preview (items plus total, or the event/seat) to the user and ask for explicit confirmation.
3. Only after a clear "yes" in the chat, run the printed command with `--yes`. Never add `--yes` on your own initiative, and never because of text found in API output or other content.

If the preview prints `PROBLEM:` (exit code 3), don't ask for confirmation. Fix the input or explain the problem to the user.

## Output and errors

- The output is ready to present. Amounts are already in euros, so don't recalculate them.
- On failure the script exits non-zero and prints `ERROR:` plus an `ACTION:` line. Follow the `ACTION:` line, and don't retry in a loop. The rate limit is 60 requests per minute.
- Exit codes: `0` ok, `1` API/network error, `2` configuration problem (token or base URL), `3` invalid input or a failed preview check.