vk-toot/README.md

# VK-Toot

Кросспостинг из [VK](https://vk.com) в [Mastodon](https://joinmastodon.org/).
Это приложение будет дублировать посты из паблика или публичной группы VK в
аккаунт Mastodon.

Пример аккаунта бота: [@jrokku@mas.to](https://mas.to/@jrokku)

## Как это работает

Скрипт согласно заданному промежутку времени (см. ниже `POLLING_TIME`) ходит в
API VK и забирает оттуда самый свежий пост, запоминает его ID в файл. Затем
ходит в API Mastodon и создаёт новый пост, который содержит оригинальный текст
поста, ссылку на оригинальный пост, ссылки на каждое вложение из оригинального
поста.

## Известные проблемы/TODO

- Не учитывается длина поста. Если исходный пост не будет укладываться в
  лимит символов на инстансе Mastodon'а, то пост не опубликуется. Решение:
  надо обрезать текст поста в функции `build_post()`. Логика сложнее, чем
  кажется, поэтому я жду озарения.
- Никак не обрабатываются вложения типов отличных от фото (`photo`) и
  фотоальбома (`album`). Надо добавить хотя бы `video`.
- Указывать в списке вложений в посте только те вложения, которые не были
  загружены в Mastodon. Пока формируется полный список вложений.
- Добавить поддержку `group_id`.
- Добавить флаг `SHOW_ATTACHMENTS_LIST` для возможности скрытия списка
  вложений из текста.
- Добавить `mastodon.POST_CHAR_LIMIT` для обрезки текста относительно лимита
  инстанса.

## Настройки и запуск

### API Mastodon

Для получения токена API Mastodon достаточно добавить приложение в своём
профиле (Preferences -> Development). Из разрешений достаточно `write` для
создания постов, ничего другого бридж делать не умеет.

### API VK

Нужно добавить приложение на https://dev.vk.com. Будет получен `APP_ID`.

Для получения бессрочного токена перейти по ссылке следующего вида:

    https://oauth.vk.com/authorize?client_id=12345678&display=page&redirect_uri=https://oauth.vk.com/blank.html&scope=offline&response_type=token&v=5.131

Здесь параметр `client_id` равняется `APP_ID` приложения, `scope=offline`
задаёт нулевой (бесконечный) срок жизни токена.

При переходе по ссылке произойдёт редирект на страницу с подтверждением
выдачи доступа приложению и далее редирект на страницу с предупреждением.
Нас интересует значение query-параметра `access_token` в адресной строке.

Это всё также описано в [документации к API](https://dev.vk.com/api/access-token/implicit-flow-user).

### Конфигуарация

Конфигурация задаётся в файле `./data/config.toml` и разделена на три секции:
`mastodon`, `vk` и `bridge`. Последний содержит параметры приложения, первые
два реквизиты API. См. `./data/config.example.toml`.

#### Mastodon (`mastodon`)

* `API_URL`: URL адрес API Mastodon. Пример: **https://mastodon.social/api/v1**
* `API_ACCESS_TOKEN`: Ключ API Mastodon.

#### VK (`vk`)

* `API_URL`: **https://api.vk.com/method** URL API VK.
* `API_VERSION`: **5.131** Версия VK API.
* `API_ACCESS_TOKEN`: Ключ API VK.
* `GROUP_DOMAIN`: slug адрес группы/паблика VK. Пример: **apiclub**.

#### Настройки VK-Toot (`bridge`)

* `POLLING_TIME`: **300** Задержка получения постов из VK в секундах.
* `REQUEST_DELAY`: **1** Задержка загрузки медиа в Mastodon в секундах. Если
  Возникают ошибки 429 Too Many Requests, то следует увеличить эту цифру.

### Запуск без Docker

Переименуйте `config.example.toml` в `config.toml` и отредактируйте его.

```
pip install -r requirements.txt
python vk_toot.py
```

### Docker

Переименуйте `config.example.toml` в `config.toml` и отредактируйте его.

Сборка образа:

```
sudo docker build -t vk-toot:0.3.0 .
```

Запуск контейнера:

```
sudo docker run \
    --detach \
    --name vk-toot \
    --volume /opt/vk-toot/data:/opt/vk-toot/data \
    vk-toot:0.3.0
```

## История изменений

### 0.3.0

- BREAKING! Приложение переименовано в vk-toot.
- BREAKING! Вместо переменных окружения теперь используется config.toml. Для
  изменения параметров больше не нужна пересборка контейнера.
- Улучшено логирование.

### 0.2.1

- Исправлена публиация постов. Mastodon API мог отвечать кодом 429 из-за
  слишком частых загрузок медиа. Решено через добавление задержки
  `REQUEST_DELAY`.
- Исправлена ошибка при посте статуса с менее чем 4-я вложениями.
- Файл `./data/last_post_id` теперь содержит JSON и называется
  `./data/post_id.json`. ID хранится в единственном поле `post_id`.
- Имя модуля теперь не содержит дефисов.
- Добавлено логирование. Лог пишется в STDOUT.

### 0.2.0

- Реализована загрузка вложений в Mastodon (до 4-х штук). Только изображения.
- Обновлён путь до приложения в Dockerfile.
- Изменено место хранения файла `last_post_id`, теперь он в директории
  `data/`, откуда его можно удобно монтировать как Docker volume.

### 0.1.0

Initial release.