# Инструкции по работе с Nextcloud (OpenClaw)

Это практический регламент для работы через skill `openclaw-nextcloud`.

## 1) Подготовка

Нужны переменные окружения:

- `NEXTCLOUD_URL` — адрес Nextcloud (например, `https://cloud.example.com`)
- `NEXTCLOUD_USER` — пользователь
- `NEXTCLOUD_TOKEN` — app password (предпочтительно)

Запуск:

```bash
node skills/openclaw-nextcloud/scripts/nextcloud.js <раздел> <команда> [опции]
```

## 2) Быстрые команды

### Заметки (Notes)

- Список: `notes list`
- Получить: `notes get --id <id>`
- Создать: `notes create --title "..." --content "..." [--category "..."]`
- Изменить: `notes edit --id <id> [--title "..."] [--content "..."] [--category "..."]`
- Удалить: `notes delete --id <id>`

### Задачи (Tasks, VTODO)

- Список: `tasks list [--calendar "..."]`
- Создать: `tasks create --title "..." [--calendar "..."] [--due "YYYY-MM-DDTHH:mm:ssZ"] [--priority 0-9] [--description "..."]`
- Изменить: `tasks edit --uid <uid> [--calendar "..."] [--title "..."] [--due "..."] [--priority 0-9] [--description "..."]`
- Завершить: `tasks complete --uid <uid> [--calendar "..."]`
- Удалить: `tasks delete --uid <uid> [--calendar "..."]`

### Календарь (Events, VEVENT)

- Список (по умолчанию 7 дней): `calendar list [--from "ISO"] [--to "ISO"]`
- Создать: `calendar create --summary "..." --start "ISO" --end "ISO" [--calendar "..."] [--description "..."]`
- Изменить: `calendar edit --uid <uid> [--calendar "..."] [--summary "..."] [--start "ISO"] [--end "ISO"] [--description "..."]`
- Удалить: `calendar delete --uid <uid> [--calendar "..."]`
- Список календарей: `calendars list [--type tasks|events]`

### Файлы (WebDAV)

- Список: `files list [--path "/"]`
- Поиск: `files search --query "..."`
- Скачать содержимое: `files get --path "/path/file.txt"`
- Загрузить текст: `files upload --path "/path/file.txt" --content "..."`
- Удалить: `files delete --path "/path/file.txt"`

### Контакты (CardDAV)

- Список: `contacts list [--addressbook "..."]`
- Получить: `contacts get --uid <uid> [--addressbook "..."]`
- Поиск: `contacts search --query "..." [--addressbook "..."]`
- Создать: `contacts create --name "..." [--addressbook "..."] [--email "..."] [--phone "..."] [--organization "..."] [--title "..."] [--note "..."]`
- Изменить: `contacts edit --uid <uid> [--addressbook "..."] [--name "..."] [--email "..."] [--phone "..."] [--organization "..."] [--title "..."] [--note "..."]`
- Удалить: `contacts delete --uid <uid> [--addressbook "..."]`
- Список адресных книг: `addressbooks list`

## 3) Рабочие правила

1. Сначала `list`/`search`, потом `edit`/`delete`.
2. UID/ID брать только из свежего `list`.
3. Для массовых изменений — сначала тест на 1 объекте.
4. Для календаря всегда задавать явные `--start` и `--end` в ISO.
5. Для задач приоритет: `0` = не задан, `1` = самый высокий, `9` = низкий.

## 4) Типовые сценарии

### Создать задачу в конкретном календаре

```bash
node skills/openclaw-nextcloud/scripts/nextcloud.js tasks create \
  --title "Проверить бэкапы" \
  --calendar "personal" \
  --due "2026-02-27T09:00:00Z" \
  --priority 3
```

### Добавить событие в календарь

```bash
node skills/openclaw-nextcloud/scripts/nextcloud.js calendar create \
  --summary "Созвон" \
  --start "2026-02-27T10:00:00Z" \
  --end "2026-02-27T10:30:00Z" \
  --calendar "personal"
```

### Найти и обновить контакт

```bash
node skills/openclaw-nextcloud/scripts/nextcloud.js contacts search --query "Иван"
node skills/openclaw-nextcloud/scripts/nextcloud.js contacts edit --uid <uid> --phone "+79990000000"
```

## 5) Диагностика

- `status:error` с 401/403 — проверить `NEXTCLOUD_USER` и `NEXTCLOUD_TOKEN`
- 404 по календарю/адресной книге — проверить имя через `calendars list` / `addressbooks list`
- Неочевидные ошибки после ручного ввода даты — перепроверить ISO-формат (`YYYY-MM-DDTHH:mm:ssZ`)

## 6) Формат результата

Скрипт возвращает JSON:

- успех: `{ "status": "success", "data": ... }`
- ошибка: `{ "status": "error", "message": "..." }`