tenderkit 0.1.0__py3-none-any.whl

tenderkit/platforms/backends.py

@@ -0,0 +1,163 @@
+"""Transport adapters extracted from pharma; legacy byte APIs remain for compatibility."""
+from pathlib import Path
+import re
+import time
+
+from tenderkit.limits import MAX_BYTES, MAX_DOCUMENTS
+
+class FetchError(Exception):
+    """A job failure with a short code shown in the panel."""
+    def __init__(self, code):
+        super().__init__(code)
+        self.code = code
+
+
+class PlatformaZakupowa:
+    """platformazakupowa.pl: the transaction page lists every attachment with a direct download link."""
+    label = 'platformazakupowa.pl'
+
+    # Waits before retrying a throttled request; the first live run was throttled after 20 files 1.5 s apart.
+    BACKOFF = (60, 180)
+
+    def __init__(self, session, delay=2.0, sleep=time.sleep):
+        from tenderkit.platforms.pz_html import BASE_URL, RATE_LIMIT_MARKER, resolve_transaction_url
+        from tenderkit.platforms.pz_html import documents_from_page
+        self.session, self.delay, self.sleep = session, delay, sleep
+        self.base, self.marker, self.parse, self.resolve = BASE_URL, RATE_LIMIT_MARKER, documents_from_page, resolve_transaction_url
+
+    def transaction(self, notice):
+        """The procedure's /transakcja/<id> page; a buyer profile is resolved by the notice's reference."""
+        url = notice['platform_url'] or ''
+        found = re.search(r'platformazakupowa\.pl/transakcja/(\d+)', url)
+        if found:
+            return f'{self.base}/transakcja/{found[1]}', False
+        profile = re.search(r'platformazakupowa\.pl/pn/([^/?#\s]+)', url)
+        if not profile:
+            raise FetchError('NOT_FOUND')
+        if not notice['reference']:
+            # Only the buyer's profile and no reference to search it by (common in TED notices).
+            raise FetchError('NO_REFERENCE')
+        try:
+            return self.resolve(profile[1], notice['reference'], session=self.session), True
+        except LookupError:
+            raise FetchError('NOT_FOUND')
+
+    def get(self, url, limit=None):
+        """The body of url; a throttled request is retried after each BACKOFF wait before failing RATE_LIMITED."""
+        limit = limit or 20 * 1024 * 1024
+        for wait in (0, *self.BACKOFF):
+            if wait:
+                self.sleep(wait)
+            response = self.session.get(url, timeout=60, stream=True)
+            try:
+                if response.status_code == 429:
+                    continue
+                if response.status_code >= 400:
+                    raise FetchError(f'HTTP_{response.status_code}')
+                content = bytearray()
+                for block in response.iter_content(1 << 16):
+                    content += block
+                    if len(content) > limit:
+                        raise FetchError('TOO_LARGE')
+            finally:
+                if hasattr(response, 'close'):
+                    response.close()
+            # The platform throttles with HTTP 200 and an HTML notice instead of the file.
+            if self.marker not in bytes(content[:4000]).decode('utf-8', errors='ignore'):
+                return bytes(content)
+        raise FetchError('RATE_LIMITED')
+
+    def list(self, notice):
+        url, resolved = self.transaction(notice)
+        return self.documents_at(url, resolved, notice['reference'])
+
+    def documents_at(self, url, resolved, reference):
+        page = self.get(url).decode('utf-8', errors='replace')
+        if resolved and key(reference) not in key(page):
+            raise FetchError('REFERENCE_MISMATCH')
+        # The origin is the folder the reader needs: the opening summary and one folder per offer, else the platform's
+        # own section column (the files of offers are listed on the page apart from the attachments table).
+        return [dict(name=d['name'], ext=None, url=d['downloadUrl'], key=d['downloadUrl'],
+                     published=d['publishedDate'], origin=d['folder'] or d.get('kind'),
+                     metadata={k: d[k] for k in ('offerId', 'hiddenName', 'attachedOffer', 'kind', 'message') if k in d}) for d in self.parse(page)]
+
+    def download(self, attachment):
+        self.sleep(self.delay)
+        return self.get(attachment['url'], limit=MAX_BYTES)
+
+
+class Marketplanet:
+    """eZamawiający (Marketplanet): server-rendered document table on the notice page, with folders for the price
+    funding, the opening of offers and the results. Each file downloads by POST with a token valid in this session."""
+    label = 'eZamawiający (Marketplanet)'
+    NOTICE = re.compile(r'/pn/[^/]+/demand/(?:notice/public/\d+/details|\d+/notice/public/details)')
+    REJECTED = ('Strona nieodnaleziona', '<html')
+
+    def __init__(self, session, delay=2.0, sleep=time.sleep):
+        from tenderkit.platforms.marketplanet_html import collect_documents, resolve_notice_url
+        self.session, self.delay, self.sleep = session, delay, sleep
+        self.collect, self.resolve = collect_documents, resolve_notice_url
+
+    def transaction(self, notice):
+        """(base, notice page, resolved); a buyer's home page is resolved by the notice's reference."""
+        url = (notice['platform_url'] or '').strip()
+        parts = re.match(r'(https?://[^/\s]*ezamawiajacy\.pl)(/[^?#\s]*)?', url)
+        if not parts:
+            raise FetchError('NOT_FOUND')
+        base = 'https://' + parts[1].split('://', 1)[1]
+        if self.NOTICE.search(parts[2] or ''):
+            return base, base + parts[2], False
+        if not notice['reference']:
+            raise FetchError('NO_REFERENCE')
+        found, _ = self.resolve(self.session, base, notice['reference'])
+        if not found:
+            raise FetchError('NOT_FOUND')
+        return base, found, True
+
+    def list(self, notice):
+        base, url, resolved = self.transaction(notice)
+        return self.documents_at(url, resolved, notice['reference'])
+
+    def documents_at(self, url, resolved, reference):
+        from urllib.parse import urlsplit
+        parts = urlsplit(url)
+        base = f'{parts.scheme}://{parts.netloc}'
+        if resolved:
+            # The search may return a single row with another reference; the page must name ours.
+            page = self.session.get(url, timeout=30)
+            if page.status_code >= 400:
+                raise FetchError(f'HTTP_{page.status_code}')
+            if key(reference) not in key(page.text):
+                raise FetchError('REFERENCE_MISMATCH')
+        return [dict(name=d['name'], ext=None, url=d['downloadUrl'], published=d['publishedDate'],
+                     origin=d['folder'] or 'Postępowanie',
+                     key=f"{url}#{d['folder'] or ''}/{d['name']}@{d['publishedDate'] or ''}")
+                for d in self.collect(self.session, base, url)]
+
+    def download(self, attachment):
+        self.sleep(self.delay)
+        response = self.session.post(attachment['url'], timeout=60, stream=True)
+        try:
+            if response.status_code >= 400:
+                raise FetchError(f'HTTP_{response.status_code}')
+            content = bytearray()
+            for block in response.iter_content(1 << 16):
+                content += block
+                if len(content) > MAX_BYTES:
+                    raise FetchError('TOO_LARGE')
+        finally:
+            if hasattr(response, 'close'):
+                response.close()
+        head = bytes(content[:2000]).decode('utf-8', errors='ignore')
+        if 'text/html' in response.headers.get('Content-Type', '') and any(m in head for m in self.REJECTED):
+            # An expired token answers with the site's HTML page instead of the file.
+            raise FetchError('DOWNLOAD_REJECTED')
+        # Names often lack an extension; the attachment header carries the file name.
+        name = re.search(r'filename\*?=(?:UTF-8\'\')?"?([^";]+)', response.headers.get('Content-Disposition', ''))
+        if name and Path(name[1]).suffix:
+            attachment['ext'] = Path(name[1]).suffix
+        return bytes(content)
+
+
+def key(value):
+    return re.sub(r'[\W_]+', '', (value or '').casefold())

tenderkit/platforms/base.py

@@ -0,0 +1,79 @@
+"""Core platform contract and compatibility wrapper for existing byte fetchers.
+
+The resolved link carries the reference check across procedure() and documents();
+one-time download tokens never become document identities.
+"""
+from dataclasses import asdict, dataclass
+import hashlib
+from pathlib import Path
+import re
+from urllib.parse import urlsplit
+
+from tenderkit.model import DocumentRef, Notice, PlatformLink
+
+
+def extension(attachment):
+    for candidate in (attachment.get('ext'), Path(attachment['url'].split('?')[0]).suffix, Path(attachment['name']).suffix):
+        ext = re.sub(r'[^a-z0-9]', '', (candidate or '').lower())
+        if ext:
+            return ext[:10]
+    return 'bin'
+
+
+@dataclass(frozen=True)
+class ResolvedLink(PlatformLink):
+    reference: str | None = None
+    resolved: bool = False
+
+
+class WorkerPlatform:
+    can_download = True
+    def __init__(self, backend):
+        self.backend = backend
+        self.name = backend.label
+
+    def matches(self, url: str) -> bool:
+        from tenderkit.platforms.session import public_platform_url
+        if not public_platform_url(url):
+            return False
+        try:
+            parsed = urlsplit(url)
+            host = (parsed.hostname or '').lower()
+        except ValueError:
+            return False
+        if parsed.scheme not in ('http', 'https'):
+            return False
+        if self.name == 'platformazakupowa.pl':
+            return host == 'platformazakupowa.pl'
+        return host == 'ezamawiajacy.pl' or host.endswith('.ezamawiajacy.pl')
+
+    def procedure(self, notice: Notice) -> PlatformLink | None:
+        if not self.matches(notice.platform_url or ''):
+            return None
+        transaction = self.backend.transaction(dict(platform_url=notice.platform_url, reference=notice.reference))
+        url, resolved = transaction[-2:]
+        return ResolvedLink(self.name, url, key=urlsplit(url).path,
+                            reference=notice.reference, resolved=resolved)
+
+    def documents(self, link: PlatformLink) -> list[DocumentRef]:
+        if link.platform != self.name or not self.matches(link.url):
+            raise ValueError('Link belongs to another platform')
+        return [DocumentRef(**item) for item in self.backend.documents_at(
+            link.url, getattr(link, 'resolved', False), getattr(link, 'reference', None))]
+
+    def download(self, ref: DocumentRef, to: Path) -> Path:
+        from tenderkit.platforms.session import public_platform_url
+        from tenderkit.platforms.backends import FetchError
+        if not public_platform_url(ref.url):
+            raise FetchError('UNSAFE_URL')
+        attachment = asdict(ref)
+        content = self.backend.download(attachment)
+        head = content[:2000].lstrip().lower()
+        if Path(ref.name).suffix.lower() not in ('.html', '.htm') and (head.startswith(b'<html') or head.startswith(b'<!doctype html')):
+            raise FetchError('DOWNLOAD_REJECTED')
+        # Never use a document-supplied name as a local path. The backend may
+        # learn the extension from Content-Disposition while downloading.
+        name = f'{hashlib.sha256(content).hexdigest()}.{extension(attachment)}'
+        destination = Path(to) / name
+        destination.write_bytes(content)
+        return destination

tenderkit/platforms/bk.py

@@ -0,0 +1,78 @@
+"""Attachments linked by a public BK2021 notice."""
+import hashlib
+from pathlib import Path
+import re
+from urllib.parse import urlsplit
+
+from tenderkit.limits import MAX_BYTES
+from tenderkit.model import DocumentRef, PlatformLink
+from tenderkit.platforms.backends import FetchError
+from tenderkit.platforms.base import extension
+from tenderkit.platforms.session import bk_platform_url
+from tenderkit.sources.bk import BASE, detail
+
+
+class BkDocuments:
+    name = 'Baza Konkurencyjności'
+
+    def __init__(self, session):
+        self.session = session
+
+    def matches(self, url):
+        return bk_platform_url(url) and re.fullmatch(r'/ogloszenia/[1-9]\d*', urlsplit(url).path) is not None
+
+    def procedure(self, notice):
+        if not self.matches(notice.platform_url or ''):
+            return None
+        key = urlsplit(notice.platform_url).path.rsplit('/', 1)[1]
+        return PlatformLink(self.name, f'{BASE}/ogloszenia/{key}', key)
+
+    def documents(self, link):
+        if link.platform != self.name or not re.fullmatch(r'[1-9]\d*', link.key or ''):
+            raise FetchError('NOT_FOUND')
+        row = detail(self.session, int(link.key))
+        refs = []
+        for entry in row['attachments']:
+            file = entry.get('file') or {}
+            key = str(file.get('id'))
+            if not re.fullmatch(r'[1-9]\d*', key) or file.get('uri') != f'/api/files/{key}':
+                raise FetchError('UNSAFE_URL')
+            refs.append(DocumentRef(name=file['name'], key=key, url=f'{BASE}/api/files/{key}',
+                                    published=row['publication_date'], origin='BK announcement'))
+        return refs
+
+    def download(self, ref, to):
+        if not re.fullmatch(r'[1-9]\d*', ref.key) or ref.url != f'{BASE}/api/files/{ref.key}':
+            raise FetchError('UNSAFE_URL')
+        response = self.session.get(ref.url, stream=True, timeout=60,
+                                    headers={'Accept': 'application/octet-stream, */*'})
+        digest = hashlib.sha256()
+        temporary = Path(to) / f'bk-{ref.key}.tmp'
+        size = 0
+        try:
+            if response.status_code >= 400:
+                raise FetchError(f'HTTP_{response.status_code}')
+            if response.url and response.url != ref.url:
+                raise FetchError('UNSAFE_URL')
+            media = response.headers.get('Content-Type', '').split(';')[0].strip().lower()
+            if media in ('text/html', 'application/json'):
+                raise FetchError('DOWNLOAD_REJECTED')
+            with temporary.open('wb') as stream:
+                for block in response.iter_content(1 << 16):
+                    if not size and block.removeprefix(b'\xef\xbb\xbf').lstrip().lower().startswith(
+                            (b'<!doctype html', b'<html', b'<head', b'<body')):
+                        raise FetchError('DOWNLOAD_REJECTED')
+                    size += len(block)
+                    if size > MAX_BYTES:
+                        raise FetchError('TOO_LARGE')
+                    digest.update(block)
+                    stream.write(block)
+            if not size:
+                raise FetchError('DOWNLOAD_REJECTED')
+            suffix = extension(dict(url=ref.url, name=ref.name))
+            destination = Path(to) / f'{digest.hexdigest()}.{suffix}'
+            temporary.replace(destination)
+            return destination
+        finally:
+            response.close()
+            temporary.unlink(missing_ok=True)

tenderkit/platforms/ezamowienia.py

@@ -0,0 +1,85 @@
+"""Public documents attached to native e-Zamówienia procedures."""
+import hashlib
+from pathlib import Path
+import re
+from urllib.parse import urlsplit
+
+from tenderkit.limits import MAX_BYTES
+from tenderkit.model import DocumentRef, PlatformLink
+from tenderkit.platforms.backends import FetchError
+from tenderkit.platforms.base import extension
+from tenderkit.platforms.session import PlatformSession, native_platform_url
+
+BASE = 'https://ezamowienia.gov.pl'
+TENDER_ID = r'ocds-148610-[a-fA-F0-9-]{36}'
+OBJECT_ID = r'[a-zA-Z0-9_-]{1,200}'
+DOWNLOAD_PATH = '/mp-readmodels/api/Tender/DownloadDocument'
+
+
+class Ezamowienia:
+    name = 'e-Zamówienia (native)'
+    can_download = True
+
+    def __init__(self, session=None):
+        self.session = session or PlatformSession()
+
+    def matches(self, url):
+        try:
+            parts = urlsplit(url)
+            return parts.scheme in ('http', 'https') and parts.hostname == 'ezamowienia.gov.pl' and not parts.username
+        except ValueError:
+            return False
+
+    def procedure(self, notice):
+        if not self.matches(notice.platform_url or ''):
+            return None
+        found = re.search(TENDER_ID, notice.platform_url or '')
+        identifier = found[0] if found else notice.procedure_id
+        if not identifier or not re.fullmatch(TENDER_ID, identifier):
+            raise FetchError('NO_REFERENCE')
+        return PlatformLink(self.name, f'{BASE}/mp-client/search/list/{identifier}', identifier)
+
+    def documents(self, link):
+        if link.platform != self.name or not re.fullmatch(TENDER_ID, link.key or ''):
+            raise FetchError('NOT_FOUND')
+        response = self.session.get(f'{BASE}/mp-readmodels/api/Search/GetTenderDocuments', params={'tenderId': link.key}, timeout=30)
+        response.raise_for_status()
+        rows = response.json()
+        if not isinstance(rows, list):
+            raise ValueError('Unexpected native document inventory')
+        return [DocumentRef(name=row['fileName'], key=row['objectId'], published=row['publishedDate'], origin='Postępowanie',
+                            url=f"{BASE}{DOWNLOAD_PATH}/{link.key}/{row['objectId']}")
+                for row in rows if row.get('publishedDate') and re.fullmatch(OBJECT_ID, row.get('objectId') or '')]
+
+    def download(self, ref, to):
+        if not native_platform_url(ref.url):
+            raise FetchError('UNSAFE_URL')
+        url = urlsplit(ref.url)
+        path = re.fullmatch(f'{DOWNLOAD_PATH}/{TENDER_ID}/({OBJECT_ID})', url.path)
+        if not path or path[1] != ref.key or url.query or url.fragment or not ref.published:
+            raise FetchError('UNSAFE_URL')
+
+        response = self.session.get(ref.url, timeout=60, stream=True,
+                                    headers={'Accept': 'application/octet-stream, */*'})
+        content = bytearray()
+        try:
+            if response.status_code >= 400:
+                raise FetchError(f'HTTP_{response.status_code}')
+            if response.url and not native_platform_url(response.url):
+                raise FetchError('UNSAFE_URL')
+            if response.headers.get('Content-Type', '').split(';')[0].strip().lower() == 'text/html':
+                raise FetchError('DOWNLOAD_REJECTED')
+            for block in response.iter_content(1 << 16):
+                if len(content) + len(block) > MAX_BYTES:
+                    raise FetchError('TOO_LARGE')
+                content.extend(block)
+        finally:
+            response.close()
+
+        head = content[:2000].removeprefix(b'\xef\xbb\xbf').lstrip().lower()
+        if not content or head.startswith((b'<!doctype html', b'<html', b'<head', b'<body')):
+            raise FetchError('DOWNLOAD_REJECTED')
+        suffix = extension(dict(url=ref.url, name=ref.name, ext=ref.ext))
+        destination = Path(to) / f'{hashlib.sha256(content).hexdigest()}.{suffix}'
+        destination.write_bytes(content)
+        return destination

tenderkit/platforms/html.py

@@ -0,0 +1,67 @@
+"""Small HTML tree for platform tables; no scripts, styles or browser execution."""
+from html.parser import HTMLParser
+
+
+class Node:
+    def __init__(self, tag='', attrs=()):
+        self.tag, self.attrs, self.children = tag, dict(attrs), []
+
+    def find_all(self, tag=None, *, attr=None, value=None, direct=False):
+        found = []
+        for child in self.children:
+            if not isinstance(child, Node):
+                continue
+            matches = (tag is None or child.tag == tag) and (attr is None or (
+                value(child.attrs.get(attr, '')) if callable(value) else
+                value in child.attrs.get(attr, '').split() if attr == 'class' else child.attrs.get(attr) == value))
+            if matches:
+                found.append(child)
+            if not direct:
+                found.extend(child.find_all(tag, attr=attr, value=value))
+        return found
+
+    def find(self, tag=None, **kwargs):
+        return next(iter(self.find_all(tag, **kwargs)), None)
+
+    def text(self, separator='', strip=True):
+        def strings(node):
+            for child in node.children:
+                if isinstance(child, str):
+                    yield child.strip() if strip else child
+                elif child.tag not in ('script', 'style'):
+                    yield from strings(child)
+        return separator.join(s for s in strings(self) if s)
+
+
+class Tree(HTMLParser):
+    VOID = {'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr'}
+
+    def __init__(self, html):
+        super().__init__(convert_charrefs=True)
+        self.root = Node()
+        self.stack = [self.root]
+        self.feed(html)
+        self.close()
+
+    def handle_starttag(self, tag, attrs):
+        # HTML tables often omit the closing tags of adjacent rows/cells.
+        if tag in ('tr', 'td', 'th') and self.stack[-1].tag == tag:
+            self.stack.pop()
+        node = Node(tag, attrs)
+        self.stack[-1].children.append(node)
+        if tag not in self.VOID:
+            self.stack.append(node)
+
+    def handle_startendtag(self, tag, attrs):
+        self.handle_starttag(tag, attrs)
+        if tag not in self.VOID:
+            self.handle_endtag(tag)
+
+    def handle_endtag(self, tag):
+        for index in range(len(self.stack) - 1, 0, -1):
+            if self.stack[index].tag == tag:
+                del self.stack[index:]
+                break
+
+    def handle_data(self, data):
+        self.stack[-1].children.append(data)

tenderkit/platforms/marketplanet_html.py

@@ -0,0 +1,128 @@
+"""Marketplanet public document tables and profile resolution (no third-party imports)."""
+import re
+from urllib.parse import urljoin
+
+ROW_SPLIT_RE = re.compile(r'(?=<tr class="fileDataRow)')
+
+NAME_RE = re.compile(r'<td class="text long">\s*(?:<a[^>]*>)?\s*([^<\n]+?)\s*(?:</a>)?\s*</td>', re.DOTALL)
+
+DATE_RE = re.compile(r'<td class="date-time">([^<]*)</td>')
+
+SIZE_RE = re.compile(r'<td class="text medium">([^<]*)</td>')
+
+DOWNLOAD_RE = re.compile(r"downloadPostUrl: '([^']+)'")
+
+FOLDER_RE = re.compile(r"enterFolderUrl: '([^']+)'")
+
+def parse_rows(html: str) -> list:
+    """Split the notice/folder page into per-document <tr> blocks and pull
+    out name/date/size plus either a download token or a nested folder URL."""
+    rows = []
+    for block in ROW_SPLIT_RE.split(html)[1:]:
+        end = block.find("</tr>")
+        block = block[:end] if end >= 0 else block
+
+        name_m = NAME_RE.search(block)
+        if not name_m:
+            continue
+        name = name_m.group(1).strip()
+        if not name:
+            continue
+
+        date_m = DATE_RE.search(block)
+        size_m = SIZE_RE.search(block)
+        download_m = DOWNLOAD_RE.search(block)
+        folder_m = FOLDER_RE.search(block)
+
+        rows.append({
+            "name": name,
+            "publishedDate": date_m.group(1).strip() if date_m else None,
+            "sizeText": size_m.group(1).strip() if size_m else None,
+            "downloadPath": download_m.group(1) if download_m else None,
+            "folderPath": folder_m.group(1) if folder_m else None,
+        })
+    return rows
+
+STATUS_TABS = ["during", "current", "expired"]
+
+DATA_ROW_RE = re.compile(r'<tr class="dataRow" id="(\d+)">\s*<td class="short">([^<]*)</td>')
+
+ORG_SLUG_RE = re.compile(r'/pn/([^/"]+)/')
+
+def resolve_notice_url(session, base_url: str, reference_number: str):
+    """Resolve a bare org homepage URL + reference number to a specific
+    notice details URL, by reading the org's real (case-sensitive) slug off
+    its home page and then using its own reference-number search across all
+    three status tabs. Returns (notice_url, status_tab) or (None, reason)."""
+    home = session.get(urljoin(base_url, "/servlet/HomeServlet"), timeout=30)
+    home.raise_for_status()
+    slug_m = ORG_SLUG_RE.search(home.text)
+    if not slug_m:
+        return None, "no org slug found on home page"
+    slug = slug_m.group(1)
+
+    for status in STATUS_TABS:
+        list_url = urljoin(base_url, f"/pn/{slug}/demand/notice/publicpzp/{status}/list")
+        response = session.get(list_url, params={"demandNumber": reference_number, "isFiredBySearchButton": "true"}, timeout=30)
+        response.raise_for_status()
+        if "Brak wynik" in response.text:
+            continue
+
+        rows = DATA_ROW_RE.findall(response.text)
+        exact_matches = [row_id for row_id, num in rows if num.strip() == reference_number]
+        if len(exact_matches) == 1:
+            return urljoin(base_url, f"/pn/{slug}/demand/notice/public/{exact_matches[0]}/details"), status
+        if len(rows) == 1:
+            return (
+                urljoin(base_url, f"/pn/{slug}/demand/notice/public/{rows[0][0]}/details"),
+                f"{status} (single row, reference text differs: {rows[0][1]!r})",
+            )
+        if len(rows) > 1:
+            return None, f"{status}: {len(rows)} ambiguous rows matched"
+
+    return None, "not found in any status tab (current/during/expired)"
+
+def collect_documents(session, base_url: str, notice_url: str, max_folder_depth: int = 2) -> list:
+    """Fetch the notice details page and recursively follow one level (or
+    two, for safety) of folder rows, returning a flat list of downloadable
+    documents. Folder-only "documents" with no nested files (rare) are
+    dropped silently.
+
+    A folder page re-renders the *entire* parent document table plus its own
+    extra row(s) appended at the end, rather than just its own contents - so
+    documents are deduplicated by name (globally unique in practice within a
+    single procedure) to avoid downloading the same main-table files once per
+    folder visited."""
+    documents = []
+    seen_names = set()
+    to_visit = [(notice_url, None, 0)]
+    seen_urls = set()
+
+    while to_visit:
+        url, folder_name, depth = to_visit.pop(0)
+        if url in seen_urls:
+            continue
+        seen_urls.add(url)
+        if len(seen_urls) > 100:
+            raise ValueError('Platform folder traversal limit reached')
+
+        response = session.get(url, timeout=30)
+        response.raise_for_status()
+        rows = parse_rows(response.text)
+
+        for row in rows:
+            if row["downloadPath"]:
+                if row["name"] in seen_names:
+                    continue
+                seen_names.add(row["name"])
+                documents.append({
+                    "name": row["name"],
+                    "folder": folder_name,
+                    "publishedDate": row["publishedDate"],
+                    "sizeText": row["sizeText"],
+                    "downloadUrl": urljoin(base_url, row["downloadPath"]),
+                })
+            elif row["folderPath"] and depth < max_folder_depth:
+                to_visit.append((urljoin(base_url, row["folderPath"]), row["name"], depth + 1))
+
+    return documents