amochka 0.3.4__py3-none-any.whl → 0.4.0__py3-none-any.whl

amochka/__init__.py

@@ -2,9 +2,17 @@
 amochka: Библиотека для работы с API amoCRM.
 """
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"
 
 from .client import AmoCRMClient, CacheConfig
+from .errors import (
+    AmoCRMError,
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
 from .etl import (
     write_ndjson,
     export_leads_to_ndjson,
@@ -18,6 +26,14 @@ from .etl import (
 __all__ = [
     "AmoCRMClient",
     "CacheConfig",
+    # Exceptions
+    "AmoCRMError",
+    "APIError",
+    "AuthenticationError",
+    "NotFoundError",
+    "RateLimitError",
+    "ValidationError",
+    # ETL functions
     "write_ndjson",
     "export_leads_to_ndjson",
     "export_contacts_to_ndjson",

amochka/client.py

@@ -1,12 +1,22 @@
 import os
+import stat
 import time
 import json
 import requests
 import logging
 from datetime import datetime
-from typing import Iterator, List, Optional, Sequence, Union
+from typing import Any, Callable, Iterator, List, Optional, Sequence, Union
 # ratelimit больше не используется - rate limiting реализован вручную через self.rate_limit
 
+from .errors import (
+    AmoCRMError,
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+
 # Создаём базовый логгер
 logger = logging.getLogger(__name__)
 if not logger.handlers:
@@ -194,8 +204,18 @@ class CacheConfig:
     def __init__(self, enabled=True, storage='file', base_dir=None, file=None, lifetime_hours='default'):
         self.enabled = enabled
         self.storage = storage.lower()
-        self.base_dir = base_dir or os.path.join(os.path.expanduser('~'), '.amocrm', 'cache')
-        self.file = file  # Для обратной совместимости с custom fields
+
+        # Валидация и нормализация base_dir для защиты от path traversal
+        if base_dir is None:
+            self.base_dir = os.path.join(os.path.expanduser('~'), '.amocrm', 'cache')
+        else:
+            self.base_dir = self._validate_path(base_dir, "base_dir")
+
+        # Валидация file для обратной совместимости
+        if file is not None:
+            self.file = self._validate_path(file, "file")
+        else:
+            self.file = None
 
         # Обработка lifetime_hours: может быть int, dict, None, или 'default'
         if lifetime_hours == 'default':
@@ -218,6 +238,29 @@ class CacheConfig:
             # Fallback на дефолтные значения
             self.lifetime_hours = self.DEFAULT_LIFETIMES.copy()
 
+    @staticmethod
+    def _validate_path(path: str, param_name: str) -> str:
+        """
+        Валидирует путь для защиты от path traversal атак.
+
+        :param path: Путь для валидации
+        :param param_name: Название параметра (для сообщения об ошибке)
+        :return: Нормализованный абсолютный путь
+        :raises ValueError: Если путь содержит path traversal символы
+        """
+        if not path or not isinstance(path, str):
+            raise ValueError(f"{param_name} must be a non-empty string")
+
+        # Разворачиваем ~ и нормализуем путь
+        normalized = os.path.normpath(os.path.expanduser(path))
+
+        # Проверяем на наличие ".." в нормализованном пути
+        # (это означает попытку выйти за пределы директории)
+        if ".." in normalized.split(os.sep):
+            raise ValueError(f"{param_name} contains path traversal sequences: {path}")
+
+        return normalized
+
     def get_lifetime(self, data_type):
         """
         Получает время жизни кэша для указанного типа данных.
@@ -288,7 +331,8 @@ class AmoCRMClient:
         :param max_retries: Максимальное количество повторных попыток при ошибках (по умолчанию 3).
         :param retry_delay: Базовая задержка между попытками в секундах (по умолчанию 1.0).
         """
-        self.base_url = base_url.rstrip('/')
+        # Валидация base_url для защиты от SSRF
+        self.base_url = self._validate_base_url(base_url)
         self.rate_limit = rate_limit if rate_limit is not None else DEFAULT_RATE_LIMIT
         self.max_retries = max_retries
         self.retry_delay = retry_delay
@@ -339,16 +383,101 @@ class AmoCRMClient:
         self._pipelines_cache = None
         self._users_cache = None
 
+        # Memory cache TTL (время жизни кэша в памяти в секундах, по умолчанию 1 час)
+        self._memory_cache_ttl = 3600
+        self._cache_timestamps = {}
+
+    @staticmethod
+    def _mask_sensitive(value: str, show_chars: int = 4) -> str:
+        """
+        Маскирует sensitive данные для безопасного логирования.
+
+        :param value: Строка для маскирования
+        :param show_chars: Количество символов для показа в начале и конце
+        :return: Замаскированная строка
+        """
+        if not value or not isinstance(value, str):
+            return "***"
+        if len(value) <= show_chars * 2:
+            return "***"
+        return f"{value[:show_chars]}...{value[-show_chars:]}"
+
+    @staticmethod
+    def _validate_base_url(base_url: str) -> str:
+        """
+        Валидирует base_url для защиты от SSRF атак.
+
+        :param base_url: URL для валидации
+        :return: Нормализованный URL (без trailing slash)
+        :raises ValueError: Если URL не соответствует разрешенным доменам amoCRM/Kommo
+        """
+        if not base_url or not isinstance(base_url, str):
+            raise ValueError("base_url must be a non-empty string")
+
+        # Приводим к lowercase для проверки
+        url_lower = base_url.lower().rstrip('/')
+
+        # Проверяем протокол (только HTTPS)
+        if not url_lower.startswith('https://'):
+            raise ValueError("base_url must use HTTPS protocol for security")
+
+        # Извлекаем домен
+        try:
+            # Удаляем протокол и разбиваем на части
+            domain_part = url_lower.replace('https://', '')
+            domain = domain_part.split('/')[0]  # Берем только домен без пути
+
+            # Разрешенные домены для amoCRM и Kommo
+            allowed_domains = [
+                '.amocrm.ru',
+                '.amocrm.com',
+                '.kommo.com',
+            ]
+
+            # Проверяем, что домен заканчивается на один из разрешенных
+            is_valid = any(domain.endswith(suffix) for suffix in allowed_domains)
+
+            if not is_valid:
+                raise ValueError(
+                    f"base_url must be an official amoCRM or Kommo domain "
+                    f"(*.amocrm.ru, *.amocrm.com, *.kommo.com), got: {domain}"
+                )
+
+        except Exception as e:
+            if isinstance(e, ValueError):
+                raise
+            raise ValueError(f"Invalid base_url format: {base_url}") from e
+
+        return base_url.rstrip('/')
+
     def load_token(self):
         """
-        Загружает токен авторизации из файла или строки, проверяет его срок действия.
+        Загружает токен авторизации из environment variables или файла, проверяет его срок действия.
         При наличии refresh_token и учётных данных пробует обновить токен.
 
+        Приоритет загрузки токенов:
+        1. Environment variables (AMOCRM_ACCESS_TOKEN, AMOCRM_REFRESH_TOKEN, и т.д.)
+        2. Файл token_file или строка JSON
+
         :return: Действительный access_token.
-        :raises Exception: Если токен не найден или истёк и нет возможности обновить.
+        :raises AuthenticationError: Если токен не найден или истёк и нет возможности обновить.
         """
         data = None
-        if os.path.exists(self.token_file):
+
+        # 1. Проверяем environment variables (приоритет)
+        env_access_token = os.environ.get('AMOCRM_ACCESS_TOKEN')
+        if env_access_token:
+            self.logger.debug("Token loaded from environment variables.")
+            data = {
+                'access_token': env_access_token,
+                'refresh_token': os.environ.get('AMOCRM_REFRESH_TOKEN'),
+                'expires_at': os.environ.get('AMOCRM_EXPIRES_AT'),
+                'client_id': os.environ.get('AMOCRM_CLIENT_ID'),
+                'client_secret': os.environ.get('AMOCRM_CLIENT_SECRET'),
+                'redirect_uri': os.environ.get('AMOCRM_REDIRECT_URI'),
+            }
+        # 2. Загружаем из файла или строки
+        elif os.path.exists(self.token_file):
             with open(self.token_file, 'r') as f:
                 data = json.load(f)
             self.logger.debug(f"Token loaded from file: {self.token_file}")
@@ -357,7 +486,9 @@ class AmoCRMClient:
                 data = json.loads(self.token_file)
                 self.logger.debug("Token parsed from provided string.")
             except Exception as e:
-                raise Exception("Токен не найден и не удалось распарсить переданное содержимое.") from e
+                raise AuthenticationError(
+                    "Токен не найден: ни в environment variables, ни в файле, ни в переданной строке."
+                ) from e
 
         self.refresh_token = data.get('refresh_token', self.refresh_token)
         self.client_id = data.get('client_id', self.client_id)
@@ -386,23 +517,25 @@ class AmoCRMClient:
             self.logger.info("Access token истёк, пробую обновить через refresh_token…")
             return self._refresh_access_token()
 
-        raise Exception("Токен истёк или некорректен, и нет данных для refresh_token. Обновите токен.")
+        raise AuthenticationError("Токен истёк или некорректен, и нет данных для refresh_token. Обновите токен.")
 
-    def _wait_for_rate_limit(self):
-        """Ожидает, если превышен лимит запросов в секунду."""
+    def _clean_old_requests(self):
+        """Удаляет запросы старше 1 секунды из истории запросов."""
         now = time.time()
-        # Удаляем запросы старше 1 секунды
         self._request_times = [t for t in self._request_times if now - t < 1.0]
 
+    def _wait_for_rate_limit(self):
+        """Ожидает, если превышен лимит запросов в секунду."""
+        self._clean_old_requests()
+
         if len(self._request_times) >= self.rate_limit:
             # Ждём до освобождения слота
-            sleep_time = 1.0 - (now - self._request_times[0])
+            sleep_time = 1.0 - (time.time() - self._request_times[0])
             if sleep_time > 0:
                 self.logger.debug(f"Rate limit: ожидание {sleep_time:.3f}с (лимит {self.rate_limit} req/s)")
                 time.sleep(sleep_time)
             # Очищаем старые записи после ожидания
-            now = time.time()
-            self._request_times = [t for t in self._request_times if now - t < 1.0]
+            self._clean_old_requests()
 
         self._request_times.append(time.time())
 
@@ -416,9 +549,13 @@ class AmoCRMClient:
         :param data: Данные, отправляемые в JSON-формате.
         :param timeout: Тайм‑аут запроса в секундах (по умолчанию 10).
         :return: Ответ в формате JSON или None (если статус 204).
-        :raises Exception: При получении кода ошибки, отличного от 200/204 после всех retry.
+        :raises APIError: При получении кода ошибки, отличного от 200/204 после всех retry.
+        :raises RateLimitError: При превышении лимита запросов (429).
+        :raises AuthenticationError: При ошибках авторизации (401).
+        :raises NotFoundError: При отсутствии ресурса (404).
         """
         url = f"{self.base_url}{endpoint}"
+        is_sensitive_endpoint = "oauth" in endpoint.lower() or "token" in endpoint.lower()
         headers = {
             "Authorization": f"Bearer {self.token}",
             "Content-Type": "application/json"
@@ -454,36 +591,55 @@ class AmoCRMClient:
                     self.logger.warning(
                         f"Получен {response.status_code}, retry через {delay:.1f}с (попытка {attempt + 1}/{self.max_retries + 1})"
                     )
-                    last_exception = Exception(f"Ошибка запроса: {response.status_code}, {response.text}")
+                    if response.status_code == 429:
+                        message = "Rate limit exceeded"
+                        if not is_sensitive_endpoint and response.text:
+                            message = f"Rate limit exceeded: {response.text[:200]}"
+                        last_exception = RateLimitError(
+                            message,
+                            retry_after=response.headers.get("Retry-After")
+                        )
+                    else:
+                        if is_sensitive_endpoint:
+                            last_exception = APIError(response.status_code, f"Request error at {endpoint}")
+                        else:
+                            last_exception = APIError(response.status_code, response.text)
                     if attempt < self.max_retries:
                         time.sleep(delay)
                         continue
                     raise last_exception
 
-                # Не-retryable ошибка (400, 403, 404 и т.д.)
-                self.logger.error(f"Request error {response.status_code}: {response.text}")
-                raise Exception(f"Ошибка запроса: {response.status_code}, {response.text}")
+                # Не-retryable ошибки (400, 403, 404 и т.д.)
+                if response.status_code == 404:
+                    self.logger.error(f"Request error {response.status_code} at {endpoint}")
+                    raise NotFoundError(f"Ресурс не найден: {endpoint}")
+                if is_sensitive_endpoint:
+                    self.logger.error(f"Request error {response.status_code} at {endpoint}")
+                    raise APIError(response.status_code, f"Request error at {endpoint}")
+                response_preview = response.text[:200] if response.text else ""
+                self.logger.error(f"Request error {response.status_code}: {response_preview}...")
+                raise APIError(response.status_code, response.text)
 
             except requests.exceptions.Timeout as e:
-                last_exception = e
+                last_exception = APIError(0, f"Timeout: {e}")
                 delay = self._calculate_retry_delay(attempt)
                 self.logger.warning(f"Timeout, retry через {delay:.1f}с (попытка {attempt + 1}/{self.max_retries + 1})")
                 if attempt < self.max_retries:
                     time.sleep(delay)
                     continue
-                raise Exception(f"Timeout после {self.max_retries + 1} попыток: {e}")
+                raise APIError(0, f"Timeout после {self.max_retries + 1} попыток: {e}")
 
             except requests.exceptions.ConnectionError as e:
-                last_exception = e
+                last_exception = APIError(0, f"Connection error: {e}")
                 delay = self._calculate_retry_delay(attempt)
                 self.logger.warning(f"Connection error, retry через {delay:.1f}с (попытка {attempt + 1}/{self.max_retries + 1})")
                 if attempt < self.max_retries:
                     time.sleep(delay)
                     continue
-                raise Exception(f"Connection error после {self.max_retries + 1} попыток: {e}")
+                raise APIError(0, f"Connection error после {self.max_retries + 1} попыток: {e}")
 
         # Если дошли сюда — исчерпали все попытки
-        raise last_exception or Exception("Неизвестная ошибка после всех retry")
+        raise last_exception or APIError(0, "Неизвестная ошибка после всех retry")
 
     def _calculate_retry_delay(self, attempt: int, response=None) -> float:
         """Вычисляет задержку перед retry с exponential backoff."""
@@ -502,7 +658,7 @@ class AmoCRMClient:
     def _refresh_access_token(self):
         """Обновляет access_token по refresh_token и сохраняет его в token_file."""
         if not all([self.refresh_token, self.client_id, self.client_secret, self.redirect_uri]):
-            raise Exception("Нельзя обновить токен: отсутствует refresh_token или client_id/client_secret/redirect_uri")
+            raise AuthenticationError("Нельзя обновить токен: отсутствует refresh_token или client_id/client_secret/redirect_uri")
 
         payload = {
             "client_id": self.client_id,
@@ -515,15 +671,16 @@ class AmoCRMClient:
         self.logger.debug(f"Refreshing token via {token_url}")
         resp = requests.post(token_url, json=payload, timeout=10)
         if resp.status_code != 200:
-            self.logger.error(f"Не удалось обновить токен: {resp.status_code} {resp.text}")
-            raise Exception(f"Не удалось обновить токен: {resp.status_code}")
+            # Не логируем response body, так как он может содержать токены
+            self.logger.error(f"Не удалось обновить токен: {resp.status_code}")
+            raise AuthenticationError(f"Не удалось обновить токен: {resp.status_code}")
 
         data = resp.json() or {}
         access_token = data.get("access_token")
         refresh_token = data.get("refresh_token", self.refresh_token)
         expires_in = data.get("expires_in")
         if not access_token:
-            raise Exception("Ответ на refresh не содержит access_token")
+            raise AuthenticationError("Ответ на refresh не содержит access_token")
 
         expires_at = None
         if expires_in:
@@ -544,7 +701,9 @@ class AmoCRMClient:
                         "client_secret": self.client_secret,
                         "redirect_uri": self.redirect_uri,
                     }, f)
-                self.logger.debug(f"Новый токен сохранён в {self.token_file}")
+                # Устанавливаем права доступа 600 (только владелец может читать/писать)
+                os.chmod(self.token_file, stat.S_IRUSR | stat.S_IWUSR)
+                self.logger.debug(f"Новый токен сохранён в {self.token_file} с правами 600")
             except Exception as exc:
                 self.logger.error(f"Не удалось сохранить обновлённый токен: {exc}")
 
@@ -581,6 +740,7 @@ class AmoCRMClient:
 
         :param data_type: Тип данных ('custom_fields', 'pipelines', 'users')
         :return: Путь к файлу кэша
+        :raises ValueError: Если путь выходит за пределы base_dir (path traversal)
         """
         # Для custom_fields используем старый путь, если указан (обратная совместимость)
         if data_type == 'custom_fields' and self.cache_config.file:
@@ -591,8 +751,18 @@ class AmoCRMClient:
 
         # Формируем имя файла: {account}_{data_type}.json
         account_name = self._extract_account_name()
-        cache_filename = f"{account_name}_{data_type}.json"
-        return os.path.join(self.cache_config.base_dir, cache_filename)
+        # Санитизация account_name: удаляем потенциально опасные символы
+        safe_account_name = account_name.replace("..", "").replace("/", "_").replace("\\", "_")
+        cache_filename = f"{safe_account_name}_{data_type}.json"
+        cache_path = os.path.join(self.cache_config.base_dir, cache_filename)
+
+        # Проверяем, что результирующий путь находится внутри base_dir
+        real_base = os.path.realpath(self.cache_config.base_dir)
+        real_cache = os.path.realpath(cache_path)
+        if not real_cache.startswith(real_base):
+            raise ValueError(f"Cache path traversal detected: {cache_path}")
+
+        return cache_path
 
     def _is_cache_valid(self, data_type, last_updated):
         """
@@ -677,6 +847,67 @@ class AmoCRMClient:
             self.logger.error(f"Error loading {data_type} cache: {e}")
             return None
 
+    def _get_cached_resource(
+        self,
+        resource_type: str,
+        fetch_callable: Callable[[], Any],
+        force_update: bool = False
+    ) -> Any:
+        """
+        Универсальный метод для трехуровневого кэширования ресурсов.
+
+        Уровни кэширования:
+        1. Memory cache (с TTL) - самый быстрый
+        2. File cache (персистентный) - средний
+        3. API request - самый медленный
+
+        :param resource_type: Тип ресурса ('custom_fields', 'pipelines', 'users')
+        :param fetch_callable: Функция для загрузки данных из API
+        :param force_update: Если True, игнорирует кэш и загружает данные из API
+        :return: Кэшированные или свежие данные
+        """
+        cache_attr = f"_{resource_type}_cache"
+
+        # 1. Проверяем memory cache
+        if not force_update:
+            cached_data = getattr(self, cache_attr, None)
+            if cached_data is not None:
+                # Проверяем TTL
+                cache_time = self._cache_timestamps.get(resource_type, 0)
+                if time.time() - cache_time < self._memory_cache_ttl:
+                    self.logger.debug(f"Using memory-cached {resource_type}.")
+                    return cached_data
+                else:
+                    # Кэш устарел, очищаем
+                    self.logger.debug(f"Memory cache for {resource_type} expired.")
+                    setattr(self, cache_attr, None)
+                    self._cache_timestamps.pop(resource_type, None)
+
+        # 2. Проверяем file cache
+        if not force_update and self.cache_config.enabled:
+            cached_data = self._load_cache(resource_type)
+            if cached_data is not None:
+                setattr(self, cache_attr, cached_data)
+                self._cache_timestamps[resource_type] = time.time()
+                self.logger.debug(f"{resource_type} loaded from file cache.")
+                return cached_data
+
+        # 3. Загружаем из API
+        self.logger.debug(f"Fetching {resource_type} from API...")
+        data = fetch_callable()
+
+        # Сохраняем в memory cache
+        setattr(self, cache_attr, data)
+        self._cache_timestamps[resource_type] = time.time()
+
+        # Сохраняем в file cache
+        if self.cache_config.enabled:
+            self._save_cache(resource_type, data)
+
+        data_count = len(data) if isinstance(data, (list, dict)) else "unknown"
+        self.logger.debug(f"Fetched {data_count} {resource_type} from API.")
+        return data
+
     def _to_timestamp(self, value: Optional[Union[int, float, str, datetime]]) -> Optional[int]:
         """
         Преобразует значение даты/времени в Unix timestamp.
@@ -725,16 +956,29 @@ class AmoCRMClient:
         endpoint: str,
         params: Optional[dict] = None,
         data_path: Sequence[str] = ("_embedded",),
+        max_pages: Optional[int] = None,
     ) -> Iterator[dict]:
         """
         Возвращает генератор, проходящий по всем страницам ответа API и
         yielding элементы коллекции.
+
+        :param endpoint: API endpoint для запроса
+        :param params: Параметры запроса
+        :param data_path: Путь к данным в response
+        :param max_pages: Максимальное количество страниц для итерации (None = без ограничений)
         """
         query = dict(params or {})
         query.setdefault("page", 1)
         query.setdefault("limit", 250)
 
+        pages_fetched = 0
+
         while True:
+            # Проверка на превышение max_pages
+            if max_pages is not None and pages_fetched >= max_pages:
+                self.logger.warning(f"Reached max_pages limit ({max_pages}), stopping pagination")
+                break
+
             response = self._make_request("GET", endpoint, params=query)
             if not response:
                 break
@@ -744,6 +988,8 @@ class AmoCRMClient:
             for item in items:
                 yield item
 
+            pages_fetched += 1
+
             total_pages = response.get("_page_count")
             if total_pages is not None:
                 has_next = query["page"] < total_pages
@@ -764,10 +1010,36 @@ class AmoCRMClient:
         include: Optional[Union[str, Sequence[str]]] = None,
         limit: int = 250,
         extra_params: Optional[dict] = None,
+        max_pages: Optional[int] = None,
     ) -> Iterator[dict]:
         """
         Итератор сделок с фильтрацией по диапазону обновления и воронкам.
-        """
+
+        :param max_pages: Максимальное количество страниц для итерации (None = без ограничений)
+        :raises ValidationError: Если параметры имеют некорректный тип или значение.
+        """
+        # Валидация limit
+        if not isinstance(limit, int):
+            raise ValidationError(f"limit must be int, got {type(limit).__name__}")
+        if not 1 <= limit <= 250:
+            raise ValidationError(f"limit must be between 1 and 250, got {limit}")
+
+        # Валидация pipeline_ids
+        if pipeline_ids is not None:
+            if isinstance(pipeline_ids, int):
+                if pipeline_ids <= 0:
+                    raise ValidationError(f"pipeline_id must be positive, got {pipeline_ids}")
+            elif isinstance(pipeline_ids, (list, tuple)):
+                if not pipeline_ids:
+                    raise ValidationError("pipeline_ids cannot be empty")
+                for pid in pipeline_ids:
+                    if isinstance(pid, int) and pid <= 0:
+                        raise ValidationError(f"pipeline_id must be positive, got {pid}")
+                    if not isinstance(pid, (int, str)):
+                        raise ValidationError(f"pipeline_id must be int or str, got {type(pid).__name__}")
+            elif not isinstance(pipeline_ids, str):
+                raise ValidationError(f"pipeline_ids must be int, str or sequence, got {type(pipeline_ids).__name__}")
+
         params = {"limit": limit, "page": 1}
         start_ts = self._to_timestamp(updated_from)
         end_ts = self._to_timestamp(updated_to)
@@ -793,7 +1065,7 @@ class AmoCRMClient:
             params.update(extra_params)
 
         yield from self._iterate_paginated(
-            "/api/v4/leads", params=params, data_path=("_embedded", "leads")
+            "/api/v4/leads", params=params, data_path=("_embedded", "leads"), max_pages=max_pages
         )
 
     def fetch_leads(self, *args, **kwargs) -> List[dict]:
@@ -809,10 +1081,36 @@ class AmoCRMClient:
         contact_ids: Optional[Union[int, Sequence[Union[int, str]]]] = None,
         limit: int = 250,
         extra_params: Optional[dict] = None,
+        max_pages: Optional[int] = None,
     ) -> Iterator[dict]:
         """
         Итератор контактов с фильтрацией по диапазону обновления или списку ID.
-        """
+
+        :param max_pages: Максимальное количество страниц для итерации (None = без ограничений)
+        :raises ValidationError: Если параметры имеют некорректный тип или значение.
+        """
+        # Валидация limit
+        if not isinstance(limit, int):
+            raise ValidationError(f"limit must be int, got {type(limit).__name__}")
+        if not 1 <= limit <= 250:
+            raise ValidationError(f"limit must be between 1 and 250, got {limit}")
+
+        # Валидация contact_ids
+        if contact_ids is not None:
+            if isinstance(contact_ids, int):
+                if contact_ids <= 0:
+                    raise ValidationError(f"contact_id must be positive, got {contact_ids}")
+            elif isinstance(contact_ids, (list, tuple)):
+                if not contact_ids:
+                    raise ValidationError("contact_ids cannot be empty")
+                for cid in contact_ids:
+                    if isinstance(cid, int) and cid <= 0:
+                        raise ValidationError(f"contact_id must be positive, got {cid}")
+                    if not isinstance(cid, (int, str)):
+                        raise ValidationError(f"contact_id must be int or str, got {type(cid).__name__}")
+            elif not isinstance(contact_ids, str):
+                raise ValidationError(f"contact_ids must be int, str or sequence, got {type(contact_ids).__name__}")
+
         params = {"limit": limit, "page": 1}
         start_ts = self._to_timestamp(updated_from)
         end_ts = self._to_timestamp(updated_to)
@@ -827,7 +1125,7 @@ class AmoCRMClient:
             params.update(extra_params)
 
         yield from self._iterate_paginated(
-            "/api/v4/contacts", params=params, data_path=("_embedded", "contacts")
+            "/api/v4/contacts", params=params, data_path=("_embedded", "contacts"), max_pages=max_pages
         )
 
     def fetch_contacts(self, *args, **kwargs) -> List[dict]:
@@ -839,6 +1137,8 @@ class AmoCRMClient:
     def get_contact_by_id(self, contact_id: Union[int, str], include: Optional[Union[str, Sequence[str]]] = None) -> dict:
         """
         Получает данные контакта по его ID.
+
+        :raises NotFoundError: Если контакт не найден
         """
         endpoint = f"/api/v4/contacts/{contact_id}"
         params = {}
@@ -849,7 +1149,7 @@ class AmoCRMClient:
                 params["with"] = ",".join(str(item) for item in include)
         data = self._make_request("GET", endpoint, params=params)
         if not data or not isinstance(data, dict) or "id" not in data:
-            raise Exception(f"Contact {contact_id} not found or invalid response.")
+            raise NotFoundError(f"Contact {contact_id} not found or invalid response.")
         return data
 
     def iter_notes(
@@ -861,10 +1161,42 @@ class AmoCRMClient:
         entity_ids: Optional[Union[int, Sequence[Union[int, str]]]] = None,
         limit: int = 250,
         extra_params: Optional[dict] = None,
+        max_pages: Optional[int] = None,
     ) -> Iterator[dict]:
         """
         Итератор примечаний для заданной сущности.
-        """
+
+        :param max_pages: Максимальное количество страниц для итерации (None = без ограничений)
+        :raises ValidationError: Если параметры имеют некорректный тип или значение.
+        """
+        # Валидация limit
+        if not isinstance(limit, int):
+            raise ValidationError(f"limit must be int, got {type(limit).__name__}")
+        if not 1 <= limit <= 250:
+            raise ValidationError(f"limit must be between 1 and 250, got {limit}")
+
+        # Валидация entity
+        if not isinstance(entity, str):
+            raise ValidationError(f"entity must be str, got {type(entity).__name__}")
+        if not entity:
+            raise ValidationError("entity cannot be empty")
+
+        # Валидация entity_ids
+        if entity_ids is not None:
+            if isinstance(entity_ids, int):
+                if entity_ids <= 0:
+                    raise ValidationError(f"entity_id must be positive, got {entity_ids}")
+            elif isinstance(entity_ids, (list, tuple)):
+                if not entity_ids:
+                    raise ValidationError("entity_ids cannot be empty")
+                for eid in entity_ids:
+                    if isinstance(eid, int) and eid <= 0:
+                        raise ValidationError(f"entity_id must be positive, got {eid}")
+                    if not isinstance(eid, (int, str)):
+                        raise ValidationError(f"entity_id must be int or str, got {type(eid).__name__}")
+            elif not isinstance(entity_ids, str):
+                raise ValidationError(f"entity_ids must be int, str or sequence, got {type(entity_ids).__name__}")
+
         mapping = {
             "lead": "leads",
             "contact": "contacts",
@@ -891,7 +1223,7 @@ class AmoCRMClient:
             params.update(extra_params)
 
         yield from self._iterate_paginated(
-            endpoint, params=params, data_path=("_embedded", "notes")
+            endpoint, params=params, data_path=("_embedded", "notes"), max_pages=max_pages
         )
 
     def fetch_notes(self, *args, **kwargs) -> List[dict]:
@@ -909,10 +1241,43 @@ class AmoCRMClient:
         created_to: Optional[Union[int, float, str, datetime]] = None,
         limit: int = 250,
         extra_params: Optional[dict] = None,
+        max_pages: Optional[int] = None,
     ) -> Iterator[dict]:
         """
         Итератор событий с фильтрацией по сущности, типам и диапазону дат.
-        """
+
+        :param max_pages: Максимальное количество страниц для итерации (None = без ограничений)
+        :raises ValidationError: Если параметры имеют некорректный тип или значение.
+        """
+        # Валидация limit
+        if not isinstance(limit, int):
+            raise ValidationError(f"limit must be int, got {type(limit).__name__}")
+        if not 1 <= limit <= 250:
+            raise ValidationError(f"limit must be between 1 and 250, got {limit}")
+
+        # Валидация entity (опционально, но должен быть строкой)
+        if entity is not None:
+            if not isinstance(entity, str):
+                raise ValidationError(f"entity must be str, got {type(entity).__name__}")
+            if not entity:
+                raise ValidationError("entity cannot be empty string")
+
+        # Валидация entity_ids
+        if entity_ids is not None:
+            if isinstance(entity_ids, int):
+                if entity_ids <= 0:
+                    raise ValidationError(f"entity_id must be positive, got {entity_ids}")
+            elif isinstance(entity_ids, (list, tuple)):
+                if not entity_ids:
+                    raise ValidationError("entity_ids cannot be empty")
+                for eid in entity_ids:
+                    if isinstance(eid, int) and eid <= 0:
+                        raise ValidationError(f"entity_id must be positive, got {eid}")
+                    if not isinstance(eid, (int, str)):
+                        raise ValidationError(f"entity_id must be int or str, got {type(eid).__name__}")
+            elif not isinstance(entity_ids, str):
+                raise ValidationError(f"entity_ids must be int, str or sequence, got {type(entity_ids).__name__}")
+
         params = {"limit": limit, "page": 1}
         if entity:
             params["filter[entity]"] = entity
@@ -932,7 +1297,7 @@ class AmoCRMClient:
             params.update(extra_params)
 
         yield from self._iterate_paginated(
-            "/api/v4/events", params=params, data_path=("_embedded", "events")
+            "/api/v4/events", params=params, data_path=("_embedded", "events"), max_pages=max_pages
         )
 
     def fetch_events(self, *args, **kwargs) -> List[dict]:
@@ -945,15 +1310,18 @@ class AmoCRMClient:
         self,
         limit: int = 250,
         extra_params: Optional[dict] = None,
+        max_pages: Optional[int] = None,
     ) -> Iterator[dict]:
         """
         Итератор пользователей аккаунта.
+
+        :param max_pages: Максимальное количество страниц для итерации (None = без ограничений)
         """
         params = {"limit": limit, "page": 1}
         if extra_params:
             params.update(extra_params)
         yield from self._iterate_paginated(
-            "/api/v4/users", params=params, data_path=("_embedded", "users")
+            "/api/v4/users", params=params, data_path=("_embedded", "users"), max_pages=max_pages
         )
 
     def fetch_users(self, *args, **kwargs) -> List[dict]:
@@ -967,53 +1335,31 @@ class AmoCRMClient:
         Возвращает список пользователей с кэшированием (по умолчанию 24 часа).
 
         Использует трехуровневое кэширование:
-        1. Memory cache (самый быстрый)
+        1. Memory cache (с TTL, самый быстрый)
         2. File cache (персистентный)
         3. API request (если кэш устарел или отсутствует)
 
         :param force_update: Если True, игнорирует кэш и загружает данные из API
         :return: Список пользователей
         """
-        # 1. Проверяем memory cache
-        if not force_update and self._users_cache is not None:
-            self.logger.debug("Using memory-cached users.")
-            return self._users_cache
-
-        # 2. Проверяем file cache
-        if not force_update and self.cache_config.enabled:
-            cached_data = self._load_cache('users')
-            if cached_data is not None:
-                self._users_cache = cached_data
-                self.logger.debug("Users loaded from file cache.")
-                return cached_data
-
-        # 3. Загружаем из API
-        self.logger.debug("Fetching users from API...")
-        users = self.fetch_users()
-
-        # Сохраняем в memory cache
-        self._users_cache = users
-
-        # Сохраняем в file cache
-        if self.cache_config.enabled:
-            self._save_cache('users', users)
-
-        self.logger.debug(f"Fetched {len(users)} users from API.")
-        return users
+        return self._get_cached_resource('users', self.fetch_users, force_update)
 
     def iter_pipelines(
         self,
         limit: int = 250,
         extra_params: Optional[dict] = None,
+        max_pages: Optional[int] = None,
     ) -> Iterator[dict]:
         """
         Итератор воронок со статусами.
+
+        :param max_pages: Максимальное количество страниц для итерации (None = без ограничений)
         """
         params = {"limit": limit, "page": 1}
         if extra_params:
             params.update(extra_params)
         yield from self._iterate_paginated(
-            "/api/v4/leads/pipelines", params=params, data_path=("_embedded", "pipelines")
+            "/api/v4/leads/pipelines", params=params, data_path=("_embedded", "pipelines"), max_pages=max_pages
         )
 
     def fetch_pipelines(self, *args, **kwargs) -> List[dict]:
@@ -1026,20 +1372,21 @@ class AmoCRMClient:
         """
         Получает данные сделки по её ID и возвращает объект Deal.
         Если данные отсутствуют или имеют неверную структуру, выбрасывается исключение.
-        
+
         :param deal_id: ID сделки для получения
         :param skip_fields_mapping: Если True, не загружает справочник кастомных полей
                                    (используйте для работы только с ID полей)
         :return: Объект Deal с данными сделки
+        :raises NotFoundError: Если сделка не найдена
         """
         endpoint = f"/api/v4/leads/{deal_id}"
         params = {'with': 'contacts,companies,catalog_elements,loss_reason,tags'}
         data = self._make_request("GET", endpoint, params=params)
-        
+
         # Проверяем, что получили данные и что они содержат ключ "id"
         if not data or not isinstance(data, dict) or "id" not in data:
             self.logger.error(f"Deal {deal_id} not found or invalid response: {data}")
-            raise Exception(f"Deal {deal_id} not found or invalid response.")
+            raise NotFoundError(f"Deal {deal_id} not found or invalid response.")
 
         custom_config = None if skip_fields_mapping else self.get_custom_fields_mapping()
         self.logger.debug(f"Deal {deal_id} data received (содержимое полей не выводится полностью).")
@@ -1083,45 +1430,12 @@ class AmoCRMClient:
                     return None
         return None
 
-    def get_custom_fields_mapping(self, force_update=False):
+    def _fetch_custom_fields_from_api(self):
         """
-        Возвращает словарь отображения кастомных полей для сделок с кэшированием (по умолчанию 24 часа).
-
-        Использует трехуровневое кэширование:
-        1. Memory cache (самый быстрый)
-        2. File cache (персистентный)
-        3. API request (если кэш устарел или отсутствует)
+        Загружает кастомные поля из API (вспомогательный метод).
 
-        :param force_update: Если True, игнорирует кэш и загружает данные из API
         :return: Словарь с кастомными полями (ключ - field_id, значение - объект поля)
         """
-        # 1. Проверяем memory cache
-        if not force_update and self._custom_fields_mapping is not None:
-            self.logger.debug("Using memory-cached custom fields mapping.")
-            return self._custom_fields_mapping
-
-        # 2. Проверяем file cache (с поддержкой старого формата)
-        if not force_update and self.cache_config.enabled:
-            # Пробуем новый формат
-            cached_data = self._load_cache('custom_fields')
-            if cached_data is not None:
-                self._custom_fields_mapping = cached_data
-                self.logger.debug("Custom fields loaded from file cache (new format).")
-                return cached_data
-
-            # Пробуем старый формат для обратной совместимости
-            legacy_cache = self._load_custom_fields_cache()
-            if legacy_cache:
-                mapping = legacy_cache.get("mapping")
-                if mapping:
-                    self._custom_fields_mapping = mapping
-                    self.logger.debug("Custom fields loaded from legacy cache format.")
-                    # Мигрируем в новый формат
-                    self._save_cache('custom_fields', mapping)
-                    return mapping
-
-        # 3. Загружаем из API
-        self.logger.debug("Fetching custom fields from API...")
         mapping = {}
         page = 1
         total_pages = 1
@@ -1136,16 +1450,34 @@ class AmoCRMClient:
                 page += 1
             else:
                 break
+        return mapping
 
-        # Сохраняем в memory cache
-        self._custom_fields_mapping = mapping
+    def get_custom_fields_mapping(self, force_update=False):
+        """
+        Возвращает словарь отображения кастомных полей для сделок с кэшированием (по умолчанию 24 часа).
 
-        # Сохраняем в file cache (новый формат)
-        if self.cache_config.enabled:
-            self._save_cache('custom_fields', mapping)
+        Использует трехуровневое кэширование:
+        1. Memory cache (с TTL, самый быстрый)
+        2. File cache (персистентный)
+        3. API request (если кэш устарел или отсутствует)
 
-        self.logger.debug(f"Fetched {len(mapping)} custom fields from API.")
-        return mapping
+        :param force_update: Если True, игнорирует кэш и загружает данные из API
+        :return: Словарь с кастомными полями (ключ - field_id, значение - объект поля)
+        """
+        # Проверяем legacy cache для обратной совместимости
+        if not force_update and self.cache_config.enabled and self._custom_fields_mapping is None:
+            legacy_cache = self._load_custom_fields_cache()
+            if legacy_cache:
+                mapping = legacy_cache.get("mapping")
+                if mapping:
+                    self._custom_fields_mapping = mapping
+                    self._cache_timestamps['custom_fields'] = time.time()
+                    self.logger.debug("Custom fields loaded from legacy cache format.")
+                    # Мигрируем в новый формат
+                    self._save_cache('custom_fields', mapping)
+                    return mapping
+
+        return self._get_cached_resource('custom_fields', self._fetch_custom_fields_from_api, force_update)
 
     def find_custom_field_id(self, search_term):
         """
@@ -1181,7 +1513,7 @@ class AmoCRMClient:
         :param tags_to_add: Список тегов для добавления к сделке.
         :param tags_to_delete: Список тегов для удаления из сделки.
         :return: Ответ API в формате JSON.
-        :raises Exception: Если одно из кастомных полей не найдено.
+        :raises ValidationError: Если одно из кастомных полей не найдено.
         """
         payload = {}
         standard_fields = {
@@ -1208,7 +1540,7 @@ class AmoCRMClient:
                         custom_fields.append({"field_id": field_id, "values": [field_value_dict]})
                         self.logger.debug(f"Custom field '{key}' found with id {field_id} set to {value}")
                     else:
-                        raise Exception(f"Custom field '{key}' не найден.")
+                        raise ValidationError(f"Custom field '{key}' не найден.")
         if custom_fields:
             payload["custom_fields_values"] = custom_fields
         if tags_to_add:
@@ -1412,50 +1744,25 @@ class AmoCRMClient:
         Получает список всех воронок и их статусов из amoCRM.
 
         :return: Список словарей, где каждый словарь содержит данные воронки, а также, если присутствует, вложенные статусы.
-        :raises Exception: Если данные не получены или структура ответа неверна.
+        :raises APIError: Если данные не получены или структура ответа неверна.
         """
         pipelines = self.fetch_pipelines()
         if pipelines:
             self.logger.debug(f"Получено {len(pipelines)} воронок")
             return pipelines
         self.logger.error("Не удалось получить воронки из amoCRM")
-        raise Exception("Ошибка получения воронок из amoCRM")
+        raise APIError(0, "Ошибка получения воронок из amoCRM")
 
     def get_pipelines_cached(self, force_update=False):
         """
         Возвращает список воронок с кэшированием (по умолчанию 7 дней).
 
         Использует трехуровневое кэширование:
-        1. Memory cache (самый быстрый)
+        1. Memory cache (с TTL, самый быстрый)
         2. File cache (персистентный)
         3. API request (если кэш устарел или отсутствует)
 
         :param force_update: Если True, игнорирует кэш и загружает данные из API
         :return: Список воронок со статусами
         """
-        # 1. Проверяем memory cache
-        if not force_update and self._pipelines_cache is not None:
-            self.logger.debug("Using memory-cached pipelines.")
-            return self._pipelines_cache
-
-        # 2. Проверяем file cache
-        if not force_update and self.cache_config.enabled:
-            cached_data = self._load_cache('pipelines')
-            if cached_data is not None:
-                self._pipelines_cache = cached_data
-                self.logger.debug("Pipelines loaded from file cache.")
-                return cached_data
-
-        # 3. Загружаем из API
-        self.logger.debug("Fetching pipelines from API...")
-        pipelines = self.fetch_pipelines()
-
-        # Сохраняем в memory cache
-        self._pipelines_cache = pipelines
-
-        # Сохраняем в file cache
-        if self.cache_config.enabled:
-            self._save_cache('pipelines', pipelines)
-
-        self.logger.debug(f"Fetched {len(pipelines)} pipelines from API.")
-        return pipelines
+        return self._get_cached_resource('pipelines', self.fetch_pipelines, force_update)

amochka/errors.py

@@ -0,0 +1,49 @@
+"""
+Кастомные исключения для библиотеки amochka.
+"""
+
+
+class AmoCRMError(Exception):
+    """Базовое исключение для всех ошибок amoCRM API."""
+    pass
+
+
+class AuthenticationError(AmoCRMError):
+    """Исключение при ошибках авторизации и работы с токенами."""
+    pass
+
+
+class RateLimitError(AmoCRMError):
+    """Исключение при превышении лимита запросов (429 Too Many Requests)."""
+
+    def __init__(self, message="Rate limit exceeded", retry_after=None):
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class NotFoundError(AmoCRMError):
+    """Исключение при отсутствии запрашиваемого ресурса (404 Not Found)."""
+    pass
+
+
+class APIError(AmoCRMError):
+    """Общее исключение для ошибок API."""
+
+    def __init__(self, status_code, message):
+        self.status_code = status_code
+        super().__init__(f"API error {status_code}: {message}")
+
+
+class ValidationError(AmoCRMError):
+    """Исключение при некорректных входных данных."""
+    pass
+
+
+__all__ = [
+    "AmoCRMError",
+    "AuthenticationError",
+    "RateLimitError",
+    "NotFoundError",
+    "APIError",
+    "ValidationError",
+]

{amochka-0.3.4.dist-info → amochka-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: amochka
-Version: 0.3.4
+Version: 0.4.0
 Summary: Python library for working with amoCRM API with ETL capabilities
 Author-email: Timur <timurdt@gmail.com>
 License: MIT

{amochka-0.3.4.dist-info → amochka-0.4.0.dist-info}/RECORD

@@ -1,14 +1,15 @@
-amochka/__init__.py,sha256=NFAgMbhBnrx3nF--MeY9Chpu5gtZ5kVn-QYnmO3Nhpk,620
-amochka/client.py,sha256=6QMOem31Zs7Ks6CeEQYZ8VWrB1bM47NnxV103a8jDg8,70972
+amochka/__init__.py,sha256=aF51XIVOetHHu7xVAe--atPb6LrGzDgRo8uSbJW2icg,925
+amochka/client.py,sha256=WFPlkBolKory7juyIYjqxFCw6QGN2Z7KSKlMd_KoLIY,87757
+amochka/errors.py,sha256=Rg4U9srjboQwgU3wwhAed0p3vGcc0ZhuyKHIDhYFnp8,1371
 amochka/etl.py,sha256=N8rXNFbtmlKfsYpgr7HDcP4enoj63XQPWuTDxGuMhw4,8901
 etl/__init__.py,sha256=bp9fPqbKlOc7xzs27diHEvysy1FgBrwlpX6GnR6GL9U,255
 etl/config.py,sha256=BvaGn5BSGMIfvUNNsnap04iy3BHyMOuRX81G7EiLUfE,9032
-etl/extractors.py,sha256=No8E581CSNNF0VBhWiUdoO8scfeHTRYRCHu41wzzdWY,13033
+etl/extractors.py,sha256=PqjzlmUa8FLZa1z85mP6Y0-s_TH3REqW58632JzRKUc,13047
 etl/loaders.py,sha256=x8PcDQoq2kjbd52H2VzKKz5vHzyD6DXSsb9X0foPX_U,31941
 etl/run_etl.py,sha256=LxKQLE_yUPkg7kaFmmMxrdggz27puS1VdV9NTna9e4Q,26665
 etl/transformers.py,sha256=OwYJ_9l3oqvy2Y3-umXjAGweOIqlfRI0iSiCFPrcQ8E,17867
 etl/migrations/001_create_tables.sql,sha256=YrSaZjpofC1smjYx0bM4eHQumboruIBY3fwRDlJLLSo,15749
-amochka-0.3.4.dist-info/METADATA,sha256=-62tXM6dK80u1U3NJqh_jAmGPzlRoOc1oTtdbkyUVj0,7530
-amochka-0.3.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-amochka-0.3.4.dist-info/top_level.txt,sha256=grRX8aLFG-yYKPsAqCD6sUBmdLSQeOMHsc9Dl6S7Lzo,12
-amochka-0.3.4.dist-info/RECORD,,
+amochka-0.4.0.dist-info/METADATA,sha256=c9I25LoMxn4pI0pLFAIKw3qG992_9nl5YQmLSynK-LA,7530
+amochka-0.4.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+amochka-0.4.0.dist-info/top_level.txt,sha256=grRX8aLFG-yYKPsAqCD6sUBmdLSQeOMHsc9Dl6S7Lzo,12
+amochka-0.4.0.dist-info/RECORD,,

etl/extractors.py

@@ -255,8 +255,8 @@ class AmoCRMExtractor:
         for note in self.client.iter_notes(
             entity=entity_type,
             note_type=note_type,
-            start=updated_from,
-            end=updated_to,
+            updated_from=updated_from,
+            updated_to=updated_to,
         ):
             count += 1
             if count % 100 == 0: