sud-cli 0.1.1__py3-none-any.whl

sud_cli/deadline_matrix.py

@@ -0,0 +1,99 @@
+"""Deadline matrix (control points) for a case (sud v2.7.0).
+
+Builds every applicable point from the approved ``deadline_matrix`` (legal_rules)
+without inventing base dates: a point without an anchored/assumed base event
+gets ``due_at=None`` and ``needs_anchor=True`` (правило «тексты только из реестра»).
+"""
+from __future__ import annotations
+
+from datetime import date
+from typing import Any, Dict, List, Optional, Tuple
+
+from .db import get_case, get_connection, get_latest_deadline_state, init_db
+from .legal_deadlines import calculate_deadline
+from .legal_engine import STATUS_OK, load_rules
+
+
+INSTANCE_TO_JURISDICTION = {
+    "apk": "arbitration",
+    "gpk": "general_jurisdiction",
+    "kas": "kas",
+}
+
+
+def _basis_event_and_date(latest: Optional[dict]) -> Tuple[str, Optional[date]]:
+    if not latest:
+        return "MISSING", None
+    basis = latest.get("basis")
+    if not isinstance(basis, dict):
+        return "MISSING", None
+    raw = basis.get("event_date")
+    if not raw:
+        return "MISSING", None
+    try:
+        d = date.fromisoformat(str(raw)[:10])
+    except ValueError:
+        return "MISSING", None
+    if "method" in basis:
+        return "anchored", d
+    if basis.get("assumed") is True:
+        return "assumed", d
+    return "anchored", d
+
+
+def build_matrix(
+    state_dir: Any,
+    case_id: str,
+    instance_override: Optional[str] = None,
+    rules: Optional[dict] = None,
+    as_of: Optional[str] = None,
+) -> Tuple[str, List[dict]]:
+    rules = rules or load_rules()
+    init_db(state_dir)
+    conn = get_connection(state_dir)
+    try:
+        case = get_case(conn, case_id)
+        if case is None:
+            raise ValueError(f"case not found: {case_id}")
+        instance = (instance_override or case.get("instance") or "unknown")
+        instance = str(instance).strip().lower()
+        if instance not in ("apk", "gpk", "kas", "unknown"):
+            raise ValueError(f"invalid instance: {instance}")
+
+        matrix = rules.get("deadline_matrix", {}) or {}
+        if instance in INSTANCE_TO_JURISDICTION:
+            target = INSTANCE_TO_JURISDICTION[instance]
+            keys = [k for k, v in matrix.items() if (v or {}).get("jurisdiction") == target]
+        else:
+            keys = list(matrix.keys())
+
+        points: List[dict] = []
+        for key in keys:
+            entry = matrix.get(key) or {}
+            latest = get_latest_deadline_state(conn, case_id, key)
+            state_val = latest.get("state") if latest else None
+            base_event, base_date = _basis_event_and_date(latest)
+
+            due_at = None
+            if base_date is not None:
+                try:
+                    res = calculate_deadline(deadline_key=key, event_date=base_date, rules=rules)
+                    if res.status == STATUS_OK and getattr(res, "deadline", None) is not None:
+                        due_at = res.deadline.isoformat()
+                except Exception:
+                    due_at = None
+
+            point = {
+                "key": key,
+                "norm": entry.get("legal_basis"),
+                "base_event": base_event,
+                "due_at": due_at,
+                "needs_anchor": base_date is None,
+                "state": state_val,
+            }
+            if base_date is None:
+                point["warning_basis"] = "event_date_missing"
+            points.append(point)
+        return instance, points
+    finally:
+        conn.close()

sud_cli/deadline_state.py

@@ -0,0 +1,25 @@
+from .db import (
+    anchor_deadline_state,
+    append_deadline_audit,
+    confirm_deadline_state,
+    get_latest_anchored_state,
+    get_latest_deadline_state,
+    insert_deadline_state,
+    list_all_deadline_states,
+    list_deadline_states,
+    read_deadline_audit,
+    waive_deadline_state,
+)
+
+__all__ = [
+    "anchor_deadline_state",
+    "append_deadline_audit",
+    "confirm_deadline_state",
+    "get_latest_anchored_state",
+    "get_latest_deadline_state",
+    "insert_deadline_state",
+    "list_all_deadline_states",
+    "list_deadline_states",
+    "read_deadline_audit",
+    "waive_deadline_state",
+]

sud_cli/deadlines.py

@@ -0,0 +1,8 @@
+from .db import (
+    anchor_deadline_state,
+    confirm_deadline_state,
+    list_all_deadline_states,
+    list_deadline_states,
+    read_deadline_audit,
+    waive_deadline_state,
+)

sud_cli/deadlines_state.py

@@ -0,0 +1 @@
+from .deadline_state import *

sud_cli/deferral.py

@@ -0,0 +1,5 @@
+"""Template for a state-fee deferral motion."""
+
+
+def generate_deferral(applicant, court, amount, reason):
+    return {"status": "ok", "text": f"В {court}\n\nХОДАТАЙСТВО об отсрочке уплаты государственной пошлины\n\n{applicant} просит предоставить отсрочку уплаты государственной пошлины в размере {amount} руб. на основании статьи 333.41 НК РФ и статьи 102 АПК РФ. В связи с {reason} немедленная уплата пошлины затруднительна. Согласно пункту 4 Постановления Пленума ВАС РФ № 20 суд вправе учесть имущественное положение заявителя.\n\nПриложения:\n1. Справка ИФНС об открытых банковских счетах.\n2. Справки банков об остатках денежных средств.\n3. Справки банков об отсутствии картотеки № 2 (неисполненных расчетных документов).", "legal_basis": ["ст. 333.41 НК РФ", "ст. 102 АПК РФ", "п. 4 Постановления Пленума ВАС РФ № 20"]}

sud_cli/efrsb_manual.py

@@ -0,0 +1,85 @@
+"""Ручной контур ЕФРСБ (act 25.10 §1.2): human-in-the-loop fallback.
+
+Боевой автоматизированный путь проверки банкротства — КАД (kad-search).
+ЕФРСБ закрыт за Qrator/WAF; автономный browser-адаптер запрещён актом (ст. 272 УК РФ).
+Модуль не делает сетевых запросов: формирует валидную поисковую ссылку, которую
+ОТКРЫВАЕТ ЧЕЛОВЕК в основном браузере, и интерфейс фиксации provenance в досье дела.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+BASE_URL = "https://bankrot.fedresurs.ru/"
+_METHOD = "efrsb_human_verified"  # не сеть: человек + запись реквизитов
+
+KINDS = ("ul", "ip", "fl")
+
+
+class EfrsbManualError(ValueError):
+    pass
+
+
+def _require(cond: bool, msg: str) -> None:
+    if not cond:
+        raise EfrsbManualError(msg)
+
+
+def link_plan(kind: str, *, name: Optional[str] = None, inn: Optional[str] = None,
+              ogrn: Optional[str] = None, birth_date: Optional[str] = None) -> dict:
+    """Собрать план ручной проверки ЕФРСБ (без сетевых запросов, акт 25.10)."""
+    kind = (kind or "").lower()
+    _require(kind in KINDS, f"kind должен быть одним из {KINDS}")
+    if kind == "fl":
+        _require(bool(name), "для физлица нужно ФИО (--name)")
+        query = name
+        params = {"debtorFirstName": name}
+    elif kind == "ip":
+        _require(bool(name or inn), "для ИП нужно имя или ИНН")
+        query = inn or name
+        params = {"inn": inn} if inn else {"debtorLastName": name}
+    else:
+        _require(bool(name or inn or ogrn), "для ЮЛ нужно имя/ИНН/ОГРН")
+        query = inn or ogrn or name
+        params = {"inn": inn} if inn else ({"ogrn": ogrn} if ogrn else {"name": name})
+
+    # Предзаполнение: официальный интерфейс поиска принимает строковый запрос;
+    # ссылка остаётся на главную — человек вводит запрос в защищённой форме (Qrator).
+    steps = [
+        f"Открой в основном браузере: {BASE_URL}",
+        f"Раздел «Поиск» → должник: {query}",
+        "Пройди капчу/проверку — это делает ТОЛЬКО человек",
+        "Сохрани карточку должника/публикации (номер, дата, вид сообщения)",
+        "Зафиксируй в досье: sud-cli efrsb record --case <ID> --subject ... --result ... --checked-by <кто>",
+    ]
+    return {
+        "kind": kind,
+        "base_url": BASE_URL,
+        "query": query,
+        "search_params": {k: v for k, v in params.items() if v},
+        "steps": steps,
+        "automation": "off (act 25.10: browser-адаптер запрещён; КАД — боевой путь, ЕФРСБ — ручная перепроверка)",
+        "primary_instead": "kad-search (дела о несостоятельности, категория Б) — автоматизировано",
+    }
+
+
+def record_payload(*, subject: str, result: str, checked_by: str,
+                   source_ref: Optional[str] = None,
+                   notes: Optional[str] = None) -> dict:
+    """Provenance-запись результата ручной проверки ЕФРСБ (аналог fssp record)."""
+    _require(bool(subject), "нужен --subject (ИНН/ФИО/дело)")
+    _require(result in ("found", "none", "inconclusive"),
+             "result должен быть found|none|inconclusive")
+    _require(bool(checked_by), "нужен --checked-by (кто проверял)")
+    note_bits = [f"method={_METHOD}"]
+    if source_ref:
+        note_bits.append(f"source_ref={source_ref}")
+    if notes:
+        note_bits.append(notes)
+    return {
+        "subject": subject,
+        "result": result,
+        "title": f"ЕФРСБ вручную: {subject} — {result}",
+        "note": " ".join(note_bits),
+        "checked_by": checked_by,
+        "source": "bankrot.fedresurs.ru (человек)",
+    }

sud_cli/efrsb_public.py

@@ -0,0 +1,210 @@
+"""ЕФРСБ (bankrot.fedresurs.ru) — банкротные дела ЮЛ, ИП и граждан.
+
+v0.1.0 (2026-10-20, мандат владельца: «из ru-legal берём лучшее в sud-cli»).
+Паттерн заимствован у AlsKozlov/ru-legal efrsb-коннектора (Apache-2.0) в
+clean-room стиле: их API-карта, наш транспорт (sud_netguard fail-closed),
+своя нормализация. Их коннектор не импортируется.
+
+Их задокументированные уроки, воспринятые здесь:
+  - custom User-Agent блокируется (HTTP 403) -> нужен обычный браузерный UA;
+  - Referer обязателен;
+  - не-JSON ответ => источник в degraded mode (не «данных нет»).
+
+API (public, без ключей):
+  GET /backend/companies   ?searchString=&limit=
+  GET /backend/persons     ?searchString=&birthDate=&limit=
+  GET /backend/cases/<id>/publications?limit=
+  GET /backend/arbitrManagers?searchString=&inn=&sroName=
+Ответ: {"pageData": [...], ...}
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Optional
+from urllib.request import Request as _Request
+
+EFRSB_BASE = "https://bankrot.fedresurs.ru"
+EFRSB_API_BASE = f"{EFRSB_BASE}/backend"
+
+#: обычный браузерный UA: custom UA (см. ru-legal разведку) даёт 403
+_UA = ("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+       "(KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36")
+
+
+class EfrsbPublicError(Exception):
+    """Ошибка транспорта/ответа ЕФРСБ (fail-closed, без тихих деградаций)."""
+
+
+def _efrsb_http_get(url: str, *, timeout: int = 30) -> str:
+    """GET с netguard-защитой: egress fail-closed + per-host breaker."""
+    from sud_cli.sud_netguard import (
+        BreakerOpenError,
+        breaker_trip,
+        check_before_fetch,
+    )
+
+    try:
+        check_before_fetch(url)
+    except BreakerOpenError as exc:
+        raise EfrsbPublicError(
+            f"host in cooldown (anti-ban breaker): {exc}") from exc
+
+    import urllib.error as _ue
+    import urllib.request as _ur
+
+    req = _Request(url, headers={
+        "User-Agent": _UA,
+        "Accept": "application/json",
+        "Referer": f"{EFRSB_BASE}/",
+    })
+    class _NoRedirect(_ur.HTTPRedirectHandler):
+        # v2.3.3 (внешний review): efrsb обязан НЕ следовать редиректам —
+        # 302 от источника обходил DNS-pin netguard (redirect к внутренним хостам).
+        def redirect_request(self, *a, **k):
+            return None
+
+    try:
+        with _ur.build_opener(_NoRedirect()).open(req, timeout=timeout) as resp:
+            raw = resp.read(5_000_000)  # size-cap: WAF-страницы/бомбы не съедают память
+    except _ue.HTTPError as exc:
+        if exc.code in (301, 302, 303, 307, 308, 403, 429):
+            breaker_trip(url, reason=f"efrsb_http_{exc.code}")
+        # PII: searchString (ФИО/ИНН) был в тексте ошибки -> stdout/логи. Только host+path.
+        from urllib.parse import urlsplit
+        loc = urlsplit(url)
+        raise EfrsbPublicError(f"efrsb http {exc.code}: {loc.netloc}{loc.path}") from exc
+    except _ue.URLError as exc:
+        raise EfrsbPublicError("efrsb unreachable: " + str(exc.reason)[:80]) from exc
+    try:
+        return raw.decode("utf-8")
+    except UnicodeDecodeError:
+        return raw.decode("cp1251", errors="replace")
+
+
+def _api_get(path: str, params: dict[str, Any], timeout: int = 30) -> dict:
+    from urllib.parse import urlencode
+
+    qs = urlencode({k: v for k, v in params.items() if v is not None})
+    url = f"{EFRSB_API_BASE}{path}{'?' + qs if qs else ''}"
+    body = _efrsb_http_get(url, timeout=timeout)
+    try:
+        data = json.loads(body)
+    except json.JSONDecodeError as exc:
+        # их урок: не-JSON = degraded источник; для агента это error, не пустота
+        raise EfrsbPublicError("efrsb returned non-JSON (degraded source)") from exc
+    if not isinstance(data, dict):
+        raise EfrsbPublicError("efrsb returned unexpected payload type")
+    return data
+
+
+def _page_data(data: dict) -> list[dict]:
+    # v2.3.2 (sa-1 F-07): JSON-ответ источника без pageData (WAF/QRATOR-обёртка,
+    # {"pageData": null}) — это деградация источника, а не «данных нет».
+    if "pageData" not in data or data["pageData"] is None:
+        raise EfrsbPublicError("efrsb payload without pageData (degraded source)")
+    items = data["pageData"]
+    return [i for i in items if isinstance(i, dict)] if isinstance(items, list) else []
+
+
+def _row_url(item: dict, kind: str) -> Optional[str]:
+    rid = item.get("id")
+    return f"{EFRSB_BASE}/{kind}/{rid}" if rid else None
+
+
+def _normalize(item: dict) -> dict:
+    return {
+        "id": item.get("id"),
+        "name": item.get("name") or item.get("fullName") or item.get("lastName"),
+        "inn": item.get("inn"),
+        "ogrn": item.get("ogrn"),
+        "category": item.get("category"),
+        "bankrupt_type": item.get("type") or item.get("bankruptType"),
+        "case_number": item.get("caseNumber"),
+        "date": item.get("date") or item.get("publishDate"),
+        "url": _row_url(item, "bankrupt/id") if item.get("id") else None,
+        "raw_keys": sorted(k for k in item if k not in ("id", "name", "inn", "ogrn")),
+    }
+
+
+def _validate_search_args(**kwargs: Any) -> dict:
+    clean = {k: v for k, v in kwargs.items() if v}
+    if not clean:
+        raise EfrsbPublicError("нужен хотя бы один поисковый параметр")
+    if len(clean) > 1:
+        # v2.3.3 (внешний review): API принимает один searchString — «inn or ogrn or name»
+        # молча выбрасывал переданные остальные параметры. Fail-closed: просим один.
+        raise EfrsbPublicError("параметры inn/ogrn/name взаимоисключающие: передайте ровно один")
+    return clean
+
+
+def search_companies(inn: str | None = None, ogrn: str | None = None,
+                     name: str | None = None, limit: int = 5) -> dict:
+    """Банкротный поиск ЮЛ/ИП. INN(10)/ИП INN(12)/OGRN(13|15)/name>=3."""
+    args = _validate_search_args(inn=inn, ogrn=ogrn, name=name)
+    if inn and not (inn.isdigit() and len(inn) in (10, 12)):
+        raise EfrsbPublicError("ИНН должен быть 10 (ЮЛ) или 12 (ИП) цифр")
+    if ogrn and not (ogrn.isdigit() and len(ogrn) in (13, 15)):
+        raise EfrsbPublicError("ОГРН должен быть 13 (ЮЛ) или 15 (ИП) цифр")
+    if name and len(name) < 3:
+        raise EfrsbPublicError("name: минимум 3 символа")
+    search = inn or ogrn or name
+    data = _api_get("/companies", {"searchString": search, "limit": limit})
+    rows = _page_data(data)
+    return {"status": "ok" if rows else "not_found",
+            "query": search, "count": len(rows),
+            "results": [_normalize(r) for r in rows[:limit]]}
+
+
+def search_persons(full_name: str, birth_date: str | None = None,
+                   limit: int = 5) -> dict:
+    """Банкротный поиск физлиц по ФИО; birthDate (YYYY-MM-DD) сужает выборку."""
+    if len(full_name) < 3:
+        raise EfrsbPublicError("full_name: минимум 3 символа")
+    params: dict[str, Any] = {"searchString": full_name, "limit": limit}
+    if birth_date:
+        params["birthDate"] = birth_date
+    data = _api_get("/persons", params)
+    rows = _page_data(data)
+    return {"status": "ok" if rows else "not_found",
+            "query": full_name, "count": len(rows),
+            "results": [_normalize(r) for r in rows[:limit]]}
+
+
+def case_publications(case_id: str, limit: int = 10) -> dict:
+    """Публикации по делу (для слежения за конкретным банкротством)."""
+    if not case_id or "/" in case_id or ".." in case_id:
+        raise EfrsbPublicError("case_id: ожидается идентификатор дела ЕФРСБ")
+    data = _api_get(f"/cases/{case_id}/publications", {"limit": limit})
+    rows = _page_data(data)
+    return {"status": "ok" if rows else "not_found", "case_id": case_id,
+            "count": len(rows),
+            "results": [{
+                "id": r.get("id"),
+                "title": r.get("title"),
+                "date": r.get("date") or r.get("publishDate"),
+                "url": _row_url(r, "message"),
+            } for r in rows[:limit]]}
+
+
+def search_managers(search: str | None = None, inn: str | None = None,
+                    sro: str | None = None, limit: int = 5) -> dict:
+    """Арбитражные управляющие (поиск по ФИО / ИНН / СРО)."""
+    args = _validate_search_args(search=search, inn=inn, sro=sro)
+    params: dict[str, Any] = {"limit": limit}
+    if search:
+        params["searchString"] = search
+    if inn:
+        params["inn"] = inn
+    if sro:
+        params["sroName"] = sro
+    data = _api_get("/arbitrManagers", params)
+    rows = _page_data(data)
+    return {"status": "ok" if rows else "not_found",
+            "query": args, "count": len(rows),
+            "results": [{
+                "id": r.get("id"),
+                "name": r.get("name") or r.get("fullName"),
+                "inn": r.get("inn"),
+                "sro": r.get("sroName") or r.get("sro"),
+                "url": _row_url(r, "arbitrManager/id") if r.get("id") else None,
+            } for r in rows[:limit]]}

sud_cli/egrul_nalog.py

@@ -0,0 +1,150 @@
+"""egrul.nalog.ru — открытая проверка контрагента из ЕГРЮЛ/ЕГРИП (ФНС России).
+
+Контракт живой разведки 2026-10-25 (RU-egress, проверено на реальных записях):
+
+    POST https://egrul.nalog.ru/
+         form: query=<ИНН|ОГРН|название>, nameEq=, page=, vyp3CaptchaToken=
+         -> JSON {"t": "<токен>", "captchaRequired": false}
+    GET  https://egrul.nalog.ru/search-result/<t>?r=<anti-cache>
+         -> JSON {"rows": [ {...}, ... ]}  (пустой/не-JSON ответ = ещё готовится)
+
+Поля строки: c=краткое наименование, n=полное наименование, o=ОГРН, i=ИНН,
+k=тип (ul/ип), g=орган управления (ФИО), p=ОКПО, r=дата регистрации, rn=регион.
+
+Сведения ЕГРЮЛ/ЕГРИП — открытые данные ФНС (ст. 6 129-ФЗ, акты государственной
+регистрации общедоступны). Выписка vyp3 (PDF/XML) намеренно НЕ реализована:
+требует капчу и не нужна для карточки проверки.
+
+Сетевой слой: netguard (fail-closed egress, DNS-pin, per-host breaker),
+редиректы запрещены, размер ответа ограничен, строки ошибок без PII.
+"""
+from __future__ import annotations
+
+import json
+import random
+import time
+from typing import Any, Optional
+from urllib.parse import urlencode
+from urllib.request import Request as _Request
+
+EGRUL_BASE = "https://egrul.nalog.ru"
+
+#: обычный браузерный UA: сервер отдаёт JSON только непустому UA (разведка 25.10)
+_UA = ("Mozilla/5.0 (X11; Linux x86_64) Gecko/20100101 Firefox/126.0")
+
+_MAX_ATTEMPTS = 4
+_BACKOFF_S = (1.2, 2.0, 3.0)
+
+
+class EgrulError(Exception):
+    """Надёжное сообщение об ошибке без PII (запрос токена может содержать ИНН/ФИО)."""
+
+
+def _http(method: str, url: str, *, body: Optional[str] = None, timeout: int = 25) -> str:
+    """Один защищённый HTTP-обмен: netguard + no-redirect + size cap."""
+    from sud_cli.sud_netguard import (
+        BreakerOpenError,
+        breaker_trip,
+        check_before_fetch,
+    )
+
+    try:
+        check_before_fetch(url)
+    except BreakerOpenError as exc:
+        raise EgrulError(f"host in cooldown (anti-ban breaker): {exc}") from exc
+
+    import urllib.error as _ue
+    import urllib.request as _ur
+
+    headers = {
+        "User-Agent": _UA,
+        "Referer": f"{EGRUL_BASE}/",
+        "Accept": "application/json, text/html;q=0.8",
+    }
+    data = body.encode("utf-8") if body is not None else None
+    if data is not None:
+        headers["Content-Type"] = "application/x-www-form-urlencoded"
+    req = _Request(url, data=data, headers=headers, method=method)
+
+    class _NoRedirect(_ur.HTTPRedirectHandler):
+        # редирект от источника обходил бы DNS-pin netguard (см. efrsb v2.3.3)
+        def redirect_request(self, *a, **k):
+            return None
+
+    try:
+        with _ur.build_opener(_NoRedirect()).open(req, timeout=timeout) as resp:
+            raw = resp.read(2_000_000)
+    except _ue.HTTPError as exc:
+        if exc.code in (301, 302, 303, 307, 308, 403, 429):
+            breaker_trip(url, reason=f"egrul_http_{exc.code}")
+        from urllib.parse import urlsplit
+        loc = urlsplit(url)
+        raise EgrulError(f"egrul http {exc.code}: {loc.netloc}{loc.path}") from exc
+    except _ue.URLError as exc:
+        raise EgrulError("egrul unreachable: " + str(exc.reason)[:80]) from exc
+    text = raw.decode("utf-8", errors="replace")
+    return text
+
+
+def _post_query(query: str, *, exact_name: bool = False) -> str:
+    body = urlencode({
+        "query": query,
+        "nameEq": "on" if exact_name else "",
+        "page": "",
+        "vyp3CaptchaToken": "",
+    })
+    text = _http("POST", f"{EGRUL_BASE}/", body=body)
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise EgrulError("egrul: unexpected answer to query (WAF or captcha wall)") from exc
+    token = data.get("t")
+    if not token or not isinstance(token, str):
+        raise EgrulError("egrul: query rejected (no search token)")
+    if data.get("captchaRequired"):
+        raise EgrulError("egrul: captcha required, retry later")
+    return token
+
+
+def _norm_row(row: dict[str, Any]) -> dict[str, Any]:
+    kind = {"ul": "юридическое лицо", "ip": "индивидуальный предприниматель"}.get(
+        str(row.get("k")), row.get("k"))
+    return {
+        "short_name": row.get("c"),
+        "full_name": row.get("n"),
+        "ogrn": row.get("o"),
+        "inn": row.get("i"),
+        "kind": kind,
+        "governing_body": row.get("g"),
+        "okpo": row.get("p"),
+        "registration_date": row.get("r"),
+        "region": row.get("rn"),
+    }
+
+
+def search(query: str, *, exact_name: bool = False, timeout: int = 25) -> dict[str, Any]:
+    """Найти организацию/ИП в ЕГРЮЛ/ЕГРИП по ИНН, ОГРН или наименованию.
+
+    Возвращает {"query":..., "rows": [карточки...]} — только открытые сведения ФНС.
+    """
+    if not query or not str(query).strip():
+        raise EgrulError("egrul: empty query")
+    token = _post_query(str(query).strip(), exact_name=exact_name)
+    last_text = ""
+    for attempt in range(_MAX_ATTEMPTS):
+        url = f"{EGRUL_BASE}/search-result/{token}?r={random.randint(10**8, 10**9 - 1)}"
+        last_text = _http("GET", url, timeout=timeout)
+        try:
+            data = json.loads(last_text)
+        except json.JSONDecodeError:
+            data = None
+        if isinstance(data, dict) and "rows" in data:
+            return {
+                "query": str(query).strip(),
+                "rows": [_norm_row(r) for r in data.get("rows") or []],
+                "source": EGRUL_BASE,
+                "provider_label": "egrul.nalog.ru (открытые сведения ФНС)",
+            }
+        if attempt < _MAX_ATTEMPTS - 1:
+            time.sleep(_BACKOFF_S[attempt])
+    raise EgrulError("egrul: search result not ready (retry later)")