inat-channel 0.8.0.14

data/README.md

@@ -0,0 +1,150 @@
+# iNat Telegram Poster
+
+[![GitHub License](https://img.shields.io/github/license/inat-get/inat-channel)](LICENSE)
+[![Gem Version](https://badge.fury.io/rb/inat-channel.svg?icon=si%3Arubygems&d=3)](https://badge.fury.io/rb/inat-channel)
+[![Ruby](https://github.com/inat-get/inat-channel/actions/workflows/ruby.yml/badge.svg)](https://github.com/inat-get/inat-channel/actions/workflows/ruby.yml) 
+![Coverage](coverage-badge.svg)
+
+**Автоматический бот**, который ежедневно публикует в Telegram-каналы случайные, популярные наблюдения из iNaturalist, согласно гибким настройкам API-запросов.
+
+## Версия
+
++ **0.8.0** — *предварительный* релиз.
+
+## Основные возможности
+
+- Поддержка гибких запросов iNaturalist API: проекты, таксоны, места, пользователи и др.
+- Очередь публикаций с приоритетом свежих наблюдений, затем пулом и архивом отправленных (без дубликатов).
+- Поддержка до 10 фотографий и геолокационных ссылок в одном посте.
+- Вывод эмодзи и хештегов, соответствующих иерархии таксонов.
+- Автоматическая генерация ссылок на проекты и места из настройки.
+- Механизм блокировки для безопасного параллельного запуска.
+- Автоматические повторы запросов, уведомления администратору, логирование.
+
+## Быстрый старт
+
+```bash
+# 1. Установка
+bundle install
+
+# 2. Создайте конфиг (например, config.yaml)
+cat > config.yaml << EOF
+base_query:
+  project_id: 12345
+  popular: true
+  quality_grade: research
+  locale: ru
+days_back: 30
+chat_id: -1001234567890
+retries: 5
+EOF
+
+# 3. Установите переменные окружения
+export TELEGRAM_BOT_TOKEN="ваш_токен_бота"
+export ADMIN_TELEGRAM_ID="ID_администратора_в_Telegram"
+
+# 4. Запуск
+bin/inat-channel -c config.yaml
+
+# 5. Настройте cron для ежедневного запуска
+echo "0 9 * * * cd /путь/к/проекту && bin/inat-channel -c config.yaml >> log/cron.log 2>&1" | crontab -
+```
+
+## Конфигурация (пример)
+
+```yaml
+base_query:          # Параметры запроса к iNaturalist API (Hash)
+  project_id: 12345
+  popular: true
+  quality_grade: research
+  locale: ru
+days_back: 30        # Кол-во дней назад для фильтрации (integer > 0)
+chat_id: -1001234567890  # ID Telegram канала или группы
+retries: 5           # Кол-во повторных попыток запросов (API и Telegram)
+
+# Опционально — пути хранения данных (лучше использовать разные для параллельных запусков)
+pool_file: "data/pool.json"
+sent_file: "data/sent.json"
+lock_file: "data/bot.lock"
+
+# Автоссылки по place_ids
+places:
+  group:
+    - place_ids: [1, 2]
+      link: "https://inaturalist.org/projects/12345"
+      text: "Moscow Region Project"
+```
+
+## Запуск нескольких экземпляров
+
+Можно использовать несколько конфигураций для различных проектов или регионов одновременно, указав для каждого отдельные `pool_file`, `sent_file` и `lock_file`.
+
+```bash
+config/
+├── moscow.yaml       # данные: data/moscow_pool.json + moscow.lock
+└── spb.yaml          # данные: data/spb_pool.json + spb.lock
+
+bin/inat-channel -c config/moscow.yaml &
+bin/inat-channel -c config/spb.yaml &
+```
+
+Важно: файлы пула и отправленных должны быть уникальными для каждой конфигурации, чтобы избежать гонок и сбоев.
+
+## Структура директорий и данных
+
+```
+├── config.yaml        # Конфигурация (пример)
+├── data/
+│   ├── pool.json      # Кэш новых UUID объектов для публикации
+│   ├── sent.json      # UUID уже опубликованных объектов + id сообщений Telegram
+│   └── bot.lock       # Лок-файл блокировки работы бота
+├── log/               # Логи запуска бота
+└── bin/inat-channel   # Основной исполняемый файл бота
+```
+
+## Защита от параллельных запусков
+
+- Lock-файл с TTL 30 минут.
+- Автоудаление устаревших блокировок.
+- Завершение по сигналам INT и TERM (graceful shutdown).
+- Ошибка, если бот уже запущен с тем же конфигом.
+
+Пример:
+
+```bash
+$ bin/inat-channel -c config.yaml    # PID 12345 захватил lock
+$ bin/inat-channel -c config.yaml    # Ошибка: процесс с PID 12345 уже запущен
+```
+
+## Пример поста в Telegram
+
+```
+🪶 <b>Обыкновенный снегирь</b> <i>(Pyrrhula pyrrhula)</i>
+
+📷 #123456 — 👤 <a href="...">Ivan Ivanov</a> @ 📅 2025-11-15
+
+🗺️ <a href="...">Moscow Region Project</a>
+
+↳ 🗺️ 55.7558°N, 37.6173°E
+
+#Animalia • #Aves • #Pyrrhula_pyrrhula
+```
+
+## Опции командной строки
+
+```bash
+bin/inat-channel --help
+
+# Доступные параметры:
+# -c, --config FILE     Путь к конфигу (по умолчанию inat-channel.yaml)
+# -l, --log-level LEVEL Уровень логирования (debug/info/warn/error)
+# --debug               Установить уровень логирования в debug
+```
+
+## Благодарности
+
+- [iNaturalist API v2](https://www.inaturalist.org/pages/api+reference)
+- [Faraday HTTP Client](https://github.com/lostisland/faraday)
+
+**Лицензия**: [GPLv3](LICENSE)
+

data/bin/inat-channel

@@ -0,0 +1,29 @@
+#!/usr/bin/ruby
+require_relative '../lib/inat-channel'
+include INatChannel
+
+INCh::LOGGER.info "=== iNatChannel Run ==="
+
+news = INCh::API::load_news
+INCh::LOGGER.info "Found #{news.size} fresh UUIDs (days_back=#{CONFIG[:days_back]})"
+
+uuid = INCh::Data::select_uuid news
+
+if uuid
+  obs = INCh::API::load_observation(uuid)
+  if obs
+    msg_id = INCh::Telegram::send_observation(obs)
+    INCh::Data::sent[uuid] = { msg_id: msg_id, sent_at: Time.now.to_s }
+    INCh::LOGGER.info "Posted #{obs[:id]} (#{INCh::Message::list_photos(obs).size} photos)"  # очень плохо, не должно быть тут вызова list_photos
+  else
+    INCh::LOGGER.warn "Failed to load #{uuid} — returning to pool"
+    INCh::Data::pool << uuid 
+    INCh::Telegram::notify_admin "Failed to load #{uuid} — returning to pool"
+  end
+
+  INCh::Data::save
+else
+  INCh::Telegram::notify_admin 'No observation to send.'
+  INCh::LOGGER.warn 'No observation to send.'
+end
+

data/lib/inat-channel/api.rb

@@ -0,0 +1,108 @@
+require 'date'
+require 'json'
+require 'faraday'
+require 'faraday/retry'
+
+require_relative 'config'
+require_relative 'logger'
+
+module INatChannel
+
+  module API
+
+    class << self
+
+      PER_PAGE = 200
+      PAGE_DELAY = 1.0
+      API_ENDPOINT = 'https://api.inaturalist.org/v2/observations'
+      LIST_FIELDS = 'uuid'
+      SINGLE_FIELDS = '(id:!t,uuid:!t,uri:!t,geojson:(all:!t),user:(login:!t,name:!t),taxon:(ancestor_ids:!t,preferred_common_name:!t,name:!t),' +
+                      'place_ids:!t,place_guess:!t,observed_on_string:!t,description:!t,photos:(url:!t),identifications:(taxon:(ancestors:(name:!t))))'
+
+      private_constant :PER_PAGE, :PAGE_DELAY, :API_ENDPOINT, :LIST_FIELDS, :SINGLE_FIELDS
+
+      def load_news 
+        result = []
+        page = 1
+
+        loop do 
+          INatChannel::LOGGER.debug "Fetch page #{page} with per_page=#{PER_PAGE}"
+
+          response = faraday.get API_ENDPOINT do |req|
+            req.params['page'] = page
+            req.params['per_page'] = PER_PAGE
+            req.params['fields'] = LIST_FIELDS
+            req.params.merge! INatChannel::CONFIG[:base_query]
+            req.params['created_d1'] = (Date.today - INatChannel::CONFIG[:days_back]).to_s
+          end
+
+          unless response.success?
+            INatChannel::Telegram::notify_admin "Failed to fetch observations page #{page}: HTTP #{response.status}"
+            INatChannel::LOGGER.error "HTTP #{response.status} on page #{page}"
+            break
+          end
+
+          data = JSON.parse response.body, symbolize_names: true
+          uuids = data[:results].map { |o| o[:uuid] }
+          result += uuids
+
+          total = data[:total_results] || 0
+          INatChannel::LOGGER.debug "Page #{page}: fetched #{uuids.size} UUIDs, total expected #{total}"
+
+          break if uuids.empty? || result.size >= total
+          page += 1
+          sleep PAGE_DELAY
+        end
+
+        INatChannel::LOGGER.debug "Loaded total #{result.uniq.size} unique UUIDs"
+        result.uniq
+      rescue => e
+        INatChannel::Telegram::notify_admin "Exception while loading news: #{e.message}"
+        INatChannel::LOGGER.error e.full_message
+        []
+      end
+
+      def load_observation uuid
+        response = faraday.get API_ENDPOINT do |req|
+          req.params['uuid'] = uuid
+          req.params['locale'] = INatChannel::CONFIG[:base_query][:locale] if INatChannel::CONFIG[:base_query][:locale]
+          req.params['fields'] = SINGLE_FIELDS
+        end
+
+        if response.success?
+          data = JSON.parse response.body, symbolize_names: true
+          obs = data[:results]&.first
+          INatChannel::LOGGER.debug "Loaded observation: #{uuid}"
+          obs
+        else
+          INatChannel::LOGGER.error "Error loading observation #{uuid}: HTTP #{response.status}"
+          INatChannel::Telegram::notify_admin "Error loading observation #{uuid}: HTTP #{response.status}"
+          nil
+        end
+      rescue => e
+        INatChannel::Telegram::notify_admin "Exception while loading observation #{uuid}: #{e.message}"
+        INatChannel::LOGGER.error e.full_message
+        nil
+      end
+
+      private
+
+      def faraday
+        @faraday ||= Faraday::new do |f|
+          f.request :retry, max: INatChannel::CONFIG[:retries], interval: 2.0, interval_randomness: 0.5,
+                            exceptions: [ Faraday::TimeoutError, Faraday::ConnectionFailed, Faraday::SSLError, Faraday::ClientError ]
+          f.request :url_encoded
+
+          if INatChannel::LOGGER.level == ::Logger::DEBUG
+            f.response :logger, INatChannel::LOGGER, bodies: true, headers: true 
+          end
+
+          f.adapter Faraday::default_adapter
+        end
+      end
+
+    end
+
+  end
+
+end

data/lib/inat-channel/config.rb

@@ -0,0 +1,87 @@
+require 'optparse'
+require 'yaml'
+require 'logger'
+
+require_relative 'version'
+
+module INatChannel
+
+  module Config
+
+    class << self
+
+      def config
+        @config ||= get_config.freeze
+      end
+
+      private
+
+      def get_config
+        options = parse_options
+        options[:config] ||= './inat-channel.yml'
+        cfg = load_config options[:config]
+        cfg.merge! options
+        cfg[:log_level] ||= :warn
+        env = load_env
+        cfg.merge! env
+        validate_and_fix_config! cfg
+        cfg
+      end
+
+      def parse_options
+        options = {}
+        OptionParser.new do |opts|
+          opts.banner = 'Usage: inat-channel [options]'
+          opts.on '-c', '--config FILE', 'Config file (default: inat-channel.yml)' do |v|
+            raise ArgumentError, "Config file not found: #{v}" unless File.exist?(v)
+            options[:config] = v
+          end
+          opts.on '-l', '--log-level LEVEL', [:debug, :info, :warn, :error], 'Log level (default: warn)' do |v|
+            options[:log_level] = v
+          end
+          opts.on '--debug', 'Set log level to debug' do
+            options[:log_level] = :debug
+          end
+          opts.on '--version', 'Show version info and exit' do
+            puts INatChannel::VERSION
+            exit
+          end
+          opts.on '-h', '--help', 'Show help and exit' do
+            puts opts
+            exit
+          end
+        end.parse!
+        options
+      end
+
+      def load_config path
+        raise "Config file not found: #{path}" unless File.exist?(path)
+        YAML.safe_load_file(path, symbolize_names: true)
+      end
+
+      def load_env
+        { 
+          telegram_bot_token: (ENV['TELEGRAM_BOT_TOKEN'] or raise 'TELEGRAM_BOT_TOKEN required'),
+          admin_telegram_id:  (ENV['ADMIN_TELEGRAM_ID']  or raise 'ADMIN_TELEGRAM_ID required')
+        }
+      end
+
+      def validate_and_fix_config! cfg
+        raise 'Missing or invalid base_query' unless Hash === cfg[:base_query]
+        raise 'Missing or invalid days_back'  unless Integer === cfg[:days_back] && cfg[:days_back] > 0
+        raise 'Missing chat_id'               unless cfg[:chat_id]
+
+        basename = File.basename cfg[:config], '.*'
+        cfg[:pool_file] ||= "./data/#{basename}_pool.json"
+        cfg[:sent_file] ||= "./data/#{basename}_sent.json"
+        cfg[:lock_file] ||= "./data/#{basename}__bot.lock"
+        cfg[:retries]   ||= 5
+      end
+
+    end
+
+  end
+
+  CONFIG = Config::config
+
+end

data/lib/inat-channel/data.rb

@@ -0,0 +1,94 @@
+require 'time'
+require 'json'
+require 'fileutils'
+require 'set'
+
+require_relative 'config'
+require_relative 'logger'
+require_relative 'lock'
+
+module INatChannel
+
+  module Data 
+
+    class << self
+
+      def select_uuid fresh
+        INatChannel::LOGGER.info "Received #{fresh.size} uuids"
+
+        fresh.reject! { |uuid| sent?(uuid) }
+        unless fresh.empty?
+          result = fresh.sample
+          fresh.delete result
+          pool.merge fresh
+          INatChannel::LOGGER.info "Fresh uuid selected, #{fresh.size} uuids added to pool"
+          return result
+        end
+
+        pool.reject! { |uuid| sent?(uuid) }
+        unless pool.empty?
+          result = pool.to_a.sample
+          pool.delete result
+          INatChannel::LOGGER.info "Pool uuid selected, #{pool.size} uuids remain in pool"
+          return result
+        end
+
+        nil
+      end
+
+      def pool
+        @pool ||= load_pool
+      end
+
+      def sent
+        @sent ||= load_sent
+      end
+
+      def save
+        save_pool
+        save_sent
+        INatChannel::LOGGER.info "Saved pool=#{pool.size}, sent=#{sent.size}"
+      end
+
+      private
+
+      def sent? uuid
+        sent.has_key? uuid
+      end
+
+      def load_pool
+        file = INatChannel::CONFIG[:pool_file]
+        data = JSON.parse File.read(file), symbolize_names: false
+        raise "Invalid format of pool file" unless Array === data
+        Set[*data]
+      rescue
+        Set::new
+      end
+
+      def load_sent
+        file = INatChannel::CONFIG[:sent_file]
+        data = JSON.parse File.read(file), symbolize_names: false
+        raise "Invalid format of sent file" unless Hash === data
+        data
+      rescue
+        {}
+      end
+
+      def save_pool
+        pool.reject! { |uuid| sent?(uuid) }
+        file = INatChannel::CONFIG[:pool_file]
+        FileUtils.mkdir_p File.dirname(file)
+        File.write file, JSON.pretty_generate(pool.to_a)
+      end
+
+      def save_sent
+        file = INatChannel::CONFIG[:sent_file]
+        FileUtils.mkdir_p File.dirname(file)
+        File.write file, JSON.pretty_generate(sent)
+      end
+
+    end
+
+  end
+
+end

data/lib/inat-channel/icons.rb

@@ -0,0 +1,58 @@
+
+module INatChannel
+
+  module Icons
+
+    TAXA_ICONS = {
+      48460  => '🧬',
+      47126  => '🌿',
+      47170  => '🍄',
+      47686  => '🦠',
+      151817 => '🦠',
+      67333  => '🦠',
+      1      => '🐾',
+      136329 => '🌲',
+      47124  => '🌸',
+      47163  => '🍃',
+      47178  => '🐟',
+      196614 => '🦈',
+      47187  => '🦀',
+      47158  => '🪲',
+      47119  => '🕷️',
+      71261  => '🦅',
+      18874  => '🦜',
+      48222  => '🌊',
+      47115  => '🐚',
+      3      => '🐦',
+      40151  => '🦌',
+      26036  => '🐍',
+      20978  => '🐸'
+
+      # TODO: add ALL taxa with iNat icons and some other large group
+    }.freeze
+
+    ICONS = {
+      :user => '👤',
+      :place => '🗺️',
+      :calendar => '📅',
+      :location => '📍',
+      :observation => '📷',
+      :description => '📝',
+      :default_taxon => '🧬'
+      # TODO: add other icons like calendar, place, etc.
+    }.freeze
+
+    class << self
+
+      def taxon_icon taxon
+        taxon[:ancestor_ids].reverse_each do |ancestor_id|
+          return TAXA_ICONS[ancestor_id] if TAXA_ICONS[ancestor_id] 
+        end
+        return ICONS[:default_taxon]
+      end
+
+    end
+
+  end
+
+end

data/lib/inat-channel/lock.rb

@@ -0,0 +1,83 @@
+require 'time'
+require 'json'
+require 'fileutils'
+
+require_relative 'config'
+require_relative 'logger'
+
+module INatChannel
+
+  module Lock
+
+    class << self
+
+      def acquire!
+        file = INatChannel::CONFIG[:lock_file]
+        FileUtils.mkdir_p File.dirname(file)
+
+        if File.exist?(file)
+          data = load_data file
+          if stale?(data)
+            INatChannel::LOGGER.info "Remove stale lock: #{file}"
+            File.delete file
+          else
+            raise "Another instance is already running (PID: #{data[:pid]})"
+          end
+        end
+
+        data = {
+          pid: Process.pid,
+          started_at: Time.now.utc.iso8601
+        }
+        File.write file, JSON.pretty_generate(data)
+        INatChannel::LOGGER.info "Lock acquired: #{file}"
+      end
+
+      def release!
+        file = INatChannel::CONFIG[:lock_file]
+        return nil unless File.exist?(file)
+
+        File.delete file
+        INatChannel::LOGGER.info "Lock release: #{file}"
+      end
+
+      private
+
+      def load_data file
+        JSON.parse File.read(file), symbolize_names: true
+      rescue 
+        {}
+      end
+
+      LOCK_TTL = 1800  # 30 min
+
+      def stale? data
+        if data[:started_at]
+          started_at = Time.parse data[:started_at]
+          Time.now - started_at > LOCK_TTL
+        else
+          true
+        end
+      end
+
+    end
+
+    trap 'INT' do
+      self.release!
+      exit 130
+    end
+
+    trap 'TERM' do
+      self.release!
+      exit 143
+    end
+
+    at_exit do
+      self.release!
+    end
+
+    acquire!
+
+  end
+
+end

data/lib/inat-channel/logger.rb

@@ -0,0 +1,28 @@
+require_relative 'config'
+
+module INatChannel
+
+  module Logger
+
+    class << self
+
+      def logger
+        @logger ||= get_logger
+      end
+
+      private
+
+      def get_logger
+        lgr = ::Logger::new $stderr
+        lgr.level = INatChannel::CONFIG[:log_level]
+        lgr
+      end
+
+    end
+
+  end
+
+  LOGGER = Logger::logger
+
+end
+