npm package: @rvboris/sbertoactual
Description: Automating the import of Sberbank statements into Actual Budget
Author: rvboris
Latest version: 2.0.1

[🇷🇺 Русский](README.ru.md) | [🇬🇧 English](README.md)

# sbertoactual

Автоматизация импорта выписок Сбербанка (дебетовые и кредитные карты) в [Actual Budget](https://actualbudget.org/).

## Особенности

- **Поддержка форматов:** Прямой импорт CSV и PDF выписок в формате `SBER_DEBIT_2603` (использует [`@rvboris/sberparse`](https://www.npmjs.com/package/@rvboris/sberparse)).
- **Автоматизация категорий:** Автоматическое создание групп и категорий в Actual Budget на основе данных из выписки.
- **Дедупликация:** Каждая транзакция получает уникальный `imported_id` (на основе даты, суммы и описания), что предотвращает повторный импорт одних и тех же данных.
- **Два режима работы:** Гибкий CLI для локального использования и REST API сервер для интеграций.

## Быстрый старт (Docker)

Это рекомендуемый способ запуска, так как он включает все необходимые зависимости.

### Docker Compose (рекомендуется)
1. Создайте файл `.env` на основе примера в разделе "Конфигурация".
2. Запустите сервис:
```bash
docker compose up -d
```

### Docker CLI
Если вы предпочитаете обычный запуск:
```bash
docker build -t sbertoactual .
docker run -d 
  -p 3000:3000 
  -v ./data:/app/data 
  --env-file .env 
  --name sbertoactual 
  sbertoactual
```

## Локальная установка

### Требования
- **Node.js:** v24+ (согласно `.nvmrc`)
- **pnpm:** Рекомендуется (через Corepack)

### Установка зависимостей
1. Установите Node.js пакеты:
   ```bash
   pnpm install
   ```

## Конфигурация (.env)

| Переменная | Описание |
| :--- | :--- |
| `ACTUAL_SERVER_URL` | URL вашего сервера Actual Budget |
| `ACTUAL_SERVER_PASSWORD` | Пароль пользователя |
| `ACTUAL_SYNC_ID` | Sync ID вашего бюджета |
| `ACTUAL_BUDGET_PASSWORD` | Пароль шифрования бюджета (если установлен) |
| `ACTUAL_ACCOUNT_ID` | ID счета в Actual Budget, куда пойдут транзакции |
| `ACTUAL_GROUP_NAME` | Имя группы категорий. По умолчанию: "Импорт из Сбера" |
| `PORT` | Порт сервера. По умолчанию: `3000` |
| `API_KEY` | (Опционально) Секретный ключ для защиты сервера. Если установлен, запросы должны содержать заголовок `X-API-Key` |

## Использование

### Режим командной строки (CLI)
Положите файл выписки в папку `data/` и выполните команду с нужным режимом.

Доступные режимы `--mode`:

- **`all` (по умолчанию)**: Полный цикл импорта. Выполняет последовательно `convert`, `setup` и `upload`. Самый удобный способ для регулярного импорта.
- **`convert`**: Только обработка входного файла (`PDF` или `CSV`). Извлекает транзакции и сохраняет их в `actual_import.csv` для последующей обработки.
- **`setup`**: Проверка и создание категорий. Сканирует обработанные транзакции и автоматически создает недостающие категории в Actual Budget, чтобы избежать ошибок при загрузке.
- **`upload`**: Только загрузка данных. Отправляет транзакции на сервер Actual Budget. Благодаря дедупликации по `imported_id`, вы можете запускать этот режим повторно без риска дублей.
- **`list`**: Служебный режим. Выводит список всех счетов из вашего Actual Budget с их ID (помогает найти нужный `ACTUAL_ACCOUNT_ID` для конфига).

Пример запуска через `pnpm`:
```bash
# Импорт файла
env INPUT_FILE="my_statement.pdf" pnpm start -- --mode=all
```

Или через установленный глобально пакет:
```bash
sber-actual --mode=list
```

### Режим сервера (API)
Запустите сервер для автоматизации загрузки через HTTP:
```bash
pnpm run server
```

Отправьте файл выписки через `curl`. Если настроен `API_KEY`, добавьте заголовок:
```bash
# Для PDF
curl -X POST -H "X-API-Key: your-secret-key" -F "file=@statement.pdf" http://localhost:3000/upload

# Для CSV
curl -X POST -H "X-API-Key: your-secret-key" -F "file=@statement.csv" http://localhost:3000/upload
```

## Поддержка PDF

- Для PDF используется `@rvboris/sberparse`.
- Сейчас поддерживается только формат выписки `SBER_DEBIT_2603`.
- Поведение CSV-импорта не меняется.

## Разработка и тестирование

- **Проверка типов:** `pnpm run type-check`
- **Запуск тестов:** `pnpm test`
- **Линтинг:** `pnpm run lint`

## Лицензия

Проект распространяется под лицензией MIT. Подробности в файле [LICENSE](LICENSE).