bulkurlchecker 0.1.0__py3-none-any.whl

bulkurlchecker/__init__.py

@@ -0,0 +1,45 @@
+"""bulkurlchecker — Python client for the Bulk URL Checker API.
+
+Quickstart:
+
+    from bulkurlchecker import Client
+    client = Client(api_key="uck_live_...")
+    results = client.check_urls([
+        "https://example.com",
+        "https://example.org",
+    ])
+    for r in results.results:
+        print(r.url, r.status_code)
+
+Get an API key at https://app.bulkurlchecker.com/dashboard/api-keys.
+"""
+
+from ._version import __version__
+from .client import Client
+from .exceptions import (
+    AuthenticationError,
+    BulkURLCheckerError,
+    NotFoundError,
+    QuotaError,
+    RateLimitError,
+    ServerError,
+    TimeoutError,
+    ValidationError,
+)
+from .types import CheckResults, JobSummary, URLResult
+
+__all__ = [
+    "__version__",
+    "Client",
+    "CheckResults",
+    "JobSummary",
+    "URLResult",
+    "BulkURLCheckerError",
+    "AuthenticationError",
+    "RateLimitError",
+    "QuotaError",
+    "ValidationError",
+    "NotFoundError",
+    "ServerError",
+    "TimeoutError",
+]

bulkurlchecker/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

bulkurlchecker/client.py

@@ -0,0 +1,303 @@
+"""Synchronous Python client for the Bulk URL Checker REST API.
+
+Designed to be the shortest path from "I need to check 50K URLs" to
+"results are in my hands." If you find yourself writing httpx + asyncio
++ proxy rotation + per-domain rate limiting + retry classification +
+soft-404 detection, stop and use this instead.
+
+Quick example:
+
+    from bulkurlchecker import Client
+    client = Client(api_key="uck_live_...")
+    out = client.check_urls(["https://example.com", "https://example.org"])
+    for r in out.results:
+        print(r.url, r.status_code, "BROKEN" if r.is_broken else "ok")
+
+For larger jobs that exceed the synchronous wait budget, use the
+two-step pattern:
+
+    job = client.submit(my_urls)
+    # ... do other things ...
+    for batch in client.iter_results(job.job_id, page_size=1000):
+        process(batch)
+"""
+
+from __future__ import annotations
+
+import platform
+import sys
+import time
+from typing import Iterable, Iterator, List, Optional
+
+import requests
+
+from ._version import __version__
+from .exceptions import (
+    AuthenticationError,
+    BulkURLCheckerError,
+    NotFoundError,
+    QuotaError,
+    RateLimitError,
+    ServerError,
+    TimeoutError,
+    ValidationError,
+)
+from .types import CheckResults, JobSummary, URLResult
+
+
+DEFAULT_BASE_URL = "https://api.bulkurlchecker.com"
+DEFAULT_TIMEOUT = 30.0  # seconds, per HTTP call (not the wait endpoint)
+USER_AGENT_PREFIX = "bulkurlchecker-python"
+
+
+def _build_user_agent() -> str:
+    """Construct the User-Agent header.
+
+    Our server uses the bulkurlchecker- prefix to tag requests as
+    coming from an SDK so the channel telemetry can count them.
+    Including the Python + OS version helps us prioritize platform
+    support if a specific version misbehaves.
+    """
+    py = f"python/{sys.version_info.major}.{sys.version_info.minor}"
+    osinfo = f"{platform.system()}/{platform.release()}"
+    return f"{USER_AGENT_PREFIX}/{__version__} ({py}; {osinfo})"
+
+
+class Client:
+    """High-level client for the Bulk URL Checker REST API.
+
+    Args:
+        api_key: Your secret API key (looks like ``uck_live_...``).
+                 Get one from https://app.bulkurlchecker.com/dashboard/api-keys
+        base_url: Override the API host. Useful for testing against a
+                  staging deploy. Defaults to https://api.bulkurlchecker.com.
+        timeout: Per-call HTTP timeout in seconds. Does NOT bound the
+                 server-side wait inside ``check_urls()``; for that use
+                 the ``wait_seconds`` parameter.
+        session: Pre-configured ``requests.Session`` if you want to
+                 share connection pooling with the rest of your app.
+
+    Raises:
+        AuthenticationError: api_key empty or rejected.
+        RateLimitError: 429 with optional ``retry_after`` seconds.
+        QuotaError: out of credits.
+        ValidationError: malformed request (bad URLs, too many URLs).
+        NotFoundError: 404 (job_id not found / not owned).
+        ServerError: 5xx (transient, safe to retry with backoff).
+        TimeoutError: local timeout elapsed.
+        BulkURLCheckerError: catch-all parent.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        if not api_key:
+            raise AuthenticationError("api_key must be a non-empty string")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = session or requests.Session()
+        self._session.headers.update({
+            "Authorization": f"Bearer {api_key}",
+            "User-Agent": _build_user_agent(),
+            "Accept": "application/json",
+        })
+
+    # ---- Public API ----
+
+    def check_urls(
+        self,
+        urls: Iterable[str],
+        *,
+        wait_seconds: int = 60,
+        poll_interval: float = 2.0,
+    ) -> CheckResults:
+        """Submit URLs and block until results are ready (or timeout).
+
+        This is the 5-line-Python case. The server polls the job
+        on your behalf for up to ``wait_seconds`` and returns the
+        full result set in one response.
+
+        For lists > ~2,000 URLs, the wait will likely time out — use
+        ``submit()`` + ``iter_results()`` instead so you're not
+        holding an HTTP connection open for minutes.
+        """
+        urls_list = self._validate_urls(urls)
+        payload = {"urls": urls_list}
+        params = {"wait_seconds": int(wait_seconds), "poll_interval": float(poll_interval)}
+        body = self._request("POST", "/api/v2/jobs/wait", json=payload, params=params)
+        return CheckResults.from_dict(body)
+
+    def submit(self, urls: Iterable[str]) -> JobSummary:
+        """Submit a job and return immediately with the job id.
+
+        Use this when your URL list is big enough that
+        ``check_urls()`` would time out, or when you want to do
+        something else while the engine works.
+        """
+        urls_list = self._validate_urls(urls)
+        body = self._request("POST", "/api/v2/jobs", json={"urls": urls_list})
+        return JobSummary.from_dict(body)
+
+    def get_job_status(self, job_id: str) -> JobSummary:
+        """Look up the current state of a previously-submitted job."""
+        body = self._request("GET", f"/api/v2/jobs/{job_id}")
+        return JobSummary.from_dict(body)
+
+    def get_results(
+        self,
+        job_id: str,
+        *,
+        limit: int = 1000,
+        offset: int = 0,
+    ) -> List[URLResult]:
+        """Fetch one page of results. See ``iter_results()`` for streaming."""
+        params = {"limit": int(limit), "offset": int(offset)}
+        body = self._request("GET", f"/api/v2/jobs/{job_id}/results", params=params)
+        items = body.get("items") or body.get("results") or []
+        return [URLResult.from_dict(r) for r in items]
+
+    def iter_results(
+        self,
+        job_id: str,
+        *,
+        page_size: int = 1000,
+    ) -> Iterator[List[URLResult]]:
+        """Stream all results for a job in pages.
+
+        Yields lists of ``URLResult`` of at most ``page_size`` per
+        iteration. Iteration ends when the server returns an empty or
+        short page.
+        """
+        offset = 0
+        while True:
+            batch = self.get_results(job_id, limit=page_size, offset=offset)
+            if not batch:
+                return
+            yield batch
+            if len(batch) < page_size:
+                return
+            offset += page_size
+
+    def wait_until_done(
+        self,
+        job_id: str,
+        *,
+        timeout: float = 900.0,
+        poll_interval: float = 2.0,
+    ) -> JobSummary:
+        """Client-side poll loop. Returns when the job hits a terminal state.
+
+        Convenience for the "I already submitted, just block until
+        ready" case. Raises ``TimeoutError`` if the deadline passes.
+        Terminal states are: completed, failed, cancelled, paused.
+        """
+        deadline = time.monotonic() + float(timeout)
+        terminal = {"completed", "failed", "cancelled", "paused"}
+        while True:
+            job = self.get_job_status(job_id)
+            if job.status in terminal:
+                return job
+            if time.monotonic() >= deadline:
+                raise TimeoutError(
+                    f"Job {job_id} did not finish within {timeout:.0f}s "
+                    f"(last status: {job.status})"
+                )
+            time.sleep(poll_interval)
+
+    # ---- Internals ----
+
+    def _validate_urls(self, urls: Iterable[str]) -> List[str]:
+        out: List[str] = []
+        for u in urls:
+            s = (u or "").strip()
+            if not s:
+                continue
+            if not (s.lower().startswith("http://") or s.lower().startswith("https://")):
+                raise ValidationError(
+                    f"URLs must include a scheme (http:// or https://). Got: {u!r}"
+                )
+            out.append(s)
+        if not out:
+            raise ValidationError("No valid URLs provided.")
+        return out
+
+    def _request(self, method: str, path: str, **kwargs):
+        url = f"{self.base_url}{path}"
+        try:
+            resp = self._session.request(method, url, timeout=self.timeout, **kwargs)
+        except requests.Timeout as e:
+            raise TimeoutError(f"HTTP {method} {path} timed out after {self.timeout}s") from e
+        except requests.RequestException as e:
+            raise BulkURLCheckerError(
+                f"Network error calling {method} {path}: {e}"
+            ) from e
+
+        return self._handle_response(resp)
+
+    def _handle_response(self, resp: requests.Response):
+        request_id = resp.headers.get("X-Request-ID")
+        if 200 <= resp.status_code < 300:
+            try:
+                return resp.json()
+            except ValueError:
+                return {}
+
+        # Error path — try to extract the canonical {error: {code, message}}
+        # envelope. Fall back to a generic message if the body isn't JSON.
+        message = f"HTTP {resp.status_code} on {resp.request.method} {resp.url}"
+        code: Optional[str] = None
+        details = None
+        try:
+            body = resp.json()
+            err = body.get("error") if isinstance(body, dict) else None
+            if isinstance(err, dict):
+                code = err.get("code") or code
+                message = err.get("message") or message
+                details = err.get("details")
+            else:
+                # Some legacy endpoints still use `detail`
+                d = body.get("detail") if isinstance(body, dict) else None
+                if isinstance(d, str):
+                    message = d
+                elif isinstance(d, dict):
+                    code = d.get("error") or code
+                    message = d.get("message") or message
+                    details = {k: v for k, v in d.items() if k not in ("error", "message")}
+        except ValueError:
+            pass
+
+        status = resp.status_code
+        common = {
+            "status_code": status,
+            "code": code,
+            "request_id": request_id,
+            "details": details,
+        }
+        if status in (401, 403) and code == "no_credits":
+            raise QuotaError(message, **common)
+        if status in (401, 403):
+            raise AuthenticationError(message, **common)
+        if status == 404:
+            raise NotFoundError(message, **common)
+        if status == 429:
+            retry_after = None
+            ra = resp.headers.get("Retry-After")
+            if ra:
+                try:
+                    retry_after = int(float(ra))
+                except (TypeError, ValueError):
+                    retry_after = None
+            raise RateLimitError(message, retry_after=retry_after, **common)
+        if status == 402:
+            raise QuotaError(message, **common)
+        if status in (400, 422):
+            raise ValidationError(message, **common)
+        if 500 <= status < 600:
+            raise ServerError(message, **common)
+        raise BulkURLCheckerError(message, **common)

bulkurlchecker/exceptions.py

@@ -0,0 +1,77 @@
+"""Exception hierarchy for the Bulk URL Checker SDK.
+
+All errors derive from BulkURLCheckerError so callers can catch a
+single exception type and branch on it. Specific subclasses exist
+for the error categories devs actually want to handle differently:
+authentication, rate limiting, quota, and validation.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class BulkURLCheckerError(Exception):
+    """Base class for all SDK errors.
+
+    Carries the HTTP status code, the server's machine-readable
+    `error.code`, and the request_id so support requests are easy to
+    triage. Always raise the most-specific subclass possible.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        code: Optional[str] = None,
+        request_id: Optional[str] = None,
+        details: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.request_id = request_id
+        self.details = details
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging only
+        parts = [self.__class__.__name__, repr(str(self))]
+        if self.status_code is not None:
+            parts.append(f"status_code={self.status_code}")
+        if self.code:
+            parts.append(f"code={self.code!r}")
+        if self.request_id:
+            parts.append(f"request_id={self.request_id!r}")
+        return f"<{' '.join(parts)}>"
+
+
+class AuthenticationError(BulkURLCheckerError):
+    """401 / 403. The API key is missing, invalid, or revoked."""
+
+
+class RateLimitError(BulkURLCheckerError):
+    """429. Slow down. Inspect `retry_after` (seconds) if present."""
+
+    def __init__(self, *args: Any, retry_after: Optional[int] = None, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.retry_after = retry_after
+
+
+class QuotaError(BulkURLCheckerError):
+    """402 / 403 when the user has run out of credits or hit a plan limit."""
+
+
+class ValidationError(BulkURLCheckerError):
+    """400 / 422. The request was malformed (bad URLs, too many URLs, etc)."""
+
+
+class NotFoundError(BulkURLCheckerError):
+    """404. The job ID isn't owned by this API key, or doesn't exist."""
+
+
+class ServerError(BulkURLCheckerError):
+    """5xx. Transient issue on our side; safe to retry with backoff."""
+
+
+class TimeoutError(BulkURLCheckerError):  # noqa: A001 - intentional shadow
+    """The local request timeout elapsed before the server responded."""

bulkurlchecker/types.py

@@ -0,0 +1,118 @@
+"""Public response types for the Bulk URL Checker SDK.
+
+These are intentionally simple dataclasses (not pydantic models) so the
+SDK has zero runtime dependencies beyond `requests`. If you want full
+type validation, the OpenAPI spec lives at
+https://api.bulkurlchecker.com/openapi.json.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class JobSummary:
+    """High-level state of a single URL-checking job."""
+
+    job_id: str
+    status: str  # 'pending' | 'parsing' | 'processing' | 'paused' | 'completed' | 'failed' | 'cancelled'
+    total_urls: int
+    completed_urls: int = 0
+    credits_allocated: int = 0
+    duplicates_removed: int = 0
+    invalid_urls_rejected: int = 0
+    created_at: Optional[str] = None
+    started_at: Optional[str] = None
+    completed_at: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "JobSummary":
+        return cls(
+            job_id=str(d.get("job_id") or d.get("id")),
+            status=str(d.get("status") or "pending"),
+            total_urls=int(d.get("total_urls") or 0),
+            completed_urls=int(d.get("completed_urls") or 0),
+            credits_allocated=int(d.get("credits_allocated") or 0),
+            duplicates_removed=int(d.get("duplicates_removed") or 0),
+            invalid_urls_rejected=int(d.get("invalid_urls_rejected") or 0),
+            created_at=d.get("created_at"),
+            started_at=d.get("started_at"),
+            completed_at=d.get("completed_at"),
+        )
+
+
+@dataclass
+class URLResult:
+    """One URL check result. Shape mirrors the API response."""
+
+    url: str
+    final_url: Optional[str] = None
+    status_code: Optional[int] = None
+    response_time_ms: Optional[int] = None
+    redirect_chain: List[str] = field(default_factory=list)
+    is_broken: bool = False
+    is_soft_404: bool = False
+    error_code: Optional[str] = None
+    content_type: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "URLResult":
+        # The API returns slightly different field names depending on
+        # the endpoint version; this normalizer keeps the SDK shape
+        # stable across server-side changes.
+        return cls(
+            url=str(d.get("url") or ""),
+            final_url=d.get("final_url") or d.get("final"),
+            status_code=d.get("status_code") or d.get("status"),
+            response_time_ms=d.get("response_time_ms") or d.get("duration_ms"),
+            redirect_chain=list(d.get("redirect_chain") or []),
+            is_broken=bool(d.get("is_broken") or False),
+            is_soft_404=bool(d.get("is_soft_404") or False),
+            error_code=d.get("error_code") or d.get("error"),
+            content_type=d.get("content_type"),
+        )
+
+
+@dataclass
+class CheckResults:
+    """Complete result set from `Client.check_urls()` / `submit_and_wait()`."""
+
+    job_id: str
+    status: str
+    timed_out: bool
+    total_urls: int
+    completed_urls: int
+    duplicates_removed: int
+    invalid_urls_rejected: int
+    completed_at: Optional[str]
+    results: List[URLResult]
+
+    @property
+    def is_complete(self) -> bool:
+        """True when the engine finished the job within the wait window."""
+        return self.status == "completed" and not self.timed_out
+
+    @property
+    def broken(self) -> List[URLResult]:
+        """All results where the engine marked the URL broken."""
+        return [r for r in self.results if r.is_broken]
+
+    @property
+    def soft_404s(self) -> List[URLResult]:
+        return [r for r in self.results if r.is_soft_404]
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "CheckResults":
+        return cls(
+            job_id=str(d.get("job_id") or ""),
+            status=str(d.get("status") or ""),
+            timed_out=bool(d.get("timed_out") or False),
+            total_urls=int(d.get("total_urls") or 0),
+            completed_urls=int(d.get("completed_urls") or 0),
+            duplicates_removed=int(d.get("duplicates_removed") or 0),
+            invalid_urls_rejected=int(d.get("invalid_urls_rejected") or 0),
+            completed_at=d.get("completed_at"),
+            results=[URLResult.from_dict(r) for r in (d.get("results") or [])],
+        )

bulkurlchecker-0.1.0.dist-info/METADATA

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: bulkurlchecker
+Version: 0.1.0
+Summary: Python client for the Bulk URL Checker API. Skip the proxy-rotation + rate-limiter + soft-404-detector you would otherwise have to build.
+Author-email: Bulk URL Checker <carlos@bulkurlchecker.com>
+License: MIT
+Project-URL: Homepage, https://bulkurlchecker.com
+Project-URL: Documentation, https://bulkurlchecker.com/developers
+Project-URL: Source Code, https://github.com/carlosofscience/bulkurlchecker-python
+Project-URL: Bug Tracker, https://github.com/carlosofscience/bulkurlchecker-python/issues
+Project-URL: Changelog, https://github.com/carlosofscience/bulkurlchecker-python/blob/main/CHANGELOG.md
+Keywords: url-checker,bulk-url-checker,broken-link-checker,http-status-checker,seo-tools,link-validator,url-validation,redirect-checker
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-cov>=4; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Dynamic: license-file
+
+# bulkurlchecker
+
+[![PyPI version](https://img.shields.io/pypi/v/bulkurlchecker.svg)](https://pypi.org/project/bulkurlchecker/)
+[![Python versions](https://img.shields.io/pypi/pyversions/bulkurlchecker.svg)](https://pypi.org/project/bulkurlchecker/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Python client for the [Bulk URL Checker](https://bulkurlchecker.com) API.
+
+**Skip the proxy-rotation, rate-limiter, soft-404 detector, and retry classifier you would otherwise spend two weeks building.** Submit thousands of URLs, get status codes, redirect chains, and broken-link detection back as plain Python objects. Backed by a managed cloud service with residential proxies and per-domain throttling.
+
+## Install
+
+```bash
+pip install bulkurlchecker
+```
+
+## 5-line example
+
+```python
+from bulkurlchecker import Client
+
+client = Client(api_key="uck_live_...")
+results = client.check_urls(["https://example.com", "https://example.org"])
+for r in results.results:
+    print(r.url, r.status_code, "BROKEN" if r.is_broken else "ok")
+```
+
+Get an API key at https://app.bulkurlchecker.com/dashboard/api-keys. First 300 URLs are free, no card required.
+
+## What you get back
+
+```python
+results = client.check_urls(urls)
+
+results.status            # 'completed' | 'paused' | 'failed' | 'cancelled'
+results.timed_out         # True if the wait deadline passed (job still running)
+results.total_urls        # how many URLs the engine accepted
+results.completed_urls    # how many it finished checking
+results.duplicates_removed
+results.invalid_urls_rejected
+
+for r in results.results:
+    r.url                # the original URL you submitted
+    r.final_url          # after redirects
+    r.status_code        # 200, 301, 404, 429, 500, ...
+    r.redirect_chain     # list of intermediate URLs
+    r.is_broken          # True if the engine flagged this as broken
+    r.is_soft_404        # True if 200 OK but page content says "not found"
+    r.response_time_ms
+
+# Convenience properties:
+results.broken           # list of URLResult where is_broken == True
+results.soft_404s        # list where is_soft_404 == True
+```
+
+## Larger jobs: submit and poll
+
+`check_urls()` blocks for up to 15 minutes server-side. For lists where the wait would time out, use the two-step pattern:
+
+```python
+job = client.submit(my_500k_urls)
+print(f"Submitted {job.job_id}, {job.total_urls} URLs queued")
+
+# Poll explicitly, or use the convenience method
+done = client.wait_until_done(job.job_id, timeout=3600)
+
+# Stream results in pages
+for batch in client.iter_results(job.job_id, page_size=1000):
+    for r in batch:
+        if r.is_broken:
+            print(r.url, r.status_code)
+```
+
+## Error handling
+
+All errors derive from `BulkURLCheckerError`. Catch specific subclasses when you want to branch on the failure mode:
+
+```python
+from bulkurlchecker import (
+    Client,
+    BulkURLCheckerError,
+    AuthenticationError,
+    RateLimitError,
+    QuotaError,
+    ValidationError,
+)
+
+try:
+    results = client.check_urls(urls)
+except QuotaError as e:
+    print(f"Out of credits. Top up at https://app.bulkurlchecker.com/billing")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after}s.")
+except AuthenticationError:
+    print("API key rejected — check it's not revoked.")
+except ValidationError as e:
+    print(f"Bad request: {e}")  # bad URLs, too many URLs, etc.
+except BulkURLCheckerError as e:
+    print(f"Other error: {e} (request_id={e.request_id})")
+```
+
+Every error carries `status_code`, `code` (server's machine-readable string), `request_id` (for support), and `details` (when the server provides them).
+
+## Why use this instead of writing your own checker with httpx + asyncio?
+
+Honest answer: for ≤500 URLs you don't need this. The standard `requests`/`httpx` toolchain handles it fine.
+
+The wall hits at scale:
+
+| Problem | Rolling your own | This SDK |
+|---|---|---|
+| Concurrency | `asyncio` + careful semaphores | done |
+| Proxy rotation across residential IPs | $90+/mo Webshare / Bright Data subscription + custom code | done |
+| Per-domain rate limiting (so you don't hammer one host) | wire it yourself | done |
+| Distinguishing real 403 from "you got blocked" 403 | guess and check | done |
+| Detecting soft 404s (200 OK + "not found" body) | regex / heuristic per template | done |
+| Retry classification (transient vs permanent) | tune for weeks | done |
+| Long-running job state (resume after crash) | Redis + queue + worker infra | done |
+| Engineer time, weeks 1-4 | $$$ | nothing, ship today |
+
+If you've already lost a weekend to httpx + proxy rotation, you know what we're talking about.
+
+## Pricing
+
+- **Free tier:** 300 URL checks. No signup required.
+- **Starter:** $9/month or $90/year (~17% off) — 15,000 URLs/month
+- **Pro:** $29/month or $290/year — 50,000 URLs/month, 5 scheduled checks, daily monitoring
+- **Agency:** $99/month or $990/year — 200,000 URLs/month, 50 schedules, Slack + webhook alerts
+
+Top-up credit packs available beyond the monthly pool. Credits never expire.
+
+Full pricing: https://bulkurlchecker.com/#pricing
+
+## Links
+
+- [Web app](https://app.bulkurlchecker.com)
+- [REST API reference](https://bulkurlchecker.com/developers)
+- [OpenAPI spec](https://api.bulkurlchecker.com/openapi.json)
+- [GitHub](https://github.com/carlosofscience/bulkurlchecker-python)
+- [Changelog](CHANGELOG.md)
+
+## Stability
+
+The SDK follows semver. While we're at 0.x, breaking changes can land in minor releases (we'll always note them in `CHANGELOG.md`). Once we hit 1.0 you can pin major versions safely.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

bulkurlchecker-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+bulkurlchecker/__init__.py,sha256=Ms9yWEEc2yb88KrdJZrhQ7CAHL9BZRqXUrqg6NdtWsk,991
+bulkurlchecker/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+bulkurlchecker/client.py,sha256=GzOb_lARVwlFgI4SDkcHZPEWrgRGGIX3Bxd0myJKBn0,11150
+bulkurlchecker/exceptions.py,sha256=EWLXZWQmBg-pQohGRsEX45LHt9AOrmgsjzLFBQnNwfo,2528
+bulkurlchecker/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bulkurlchecker/types.py,sha256=9210KxWKV9SnghOAX6O-UUq39dq2SE7GSa09OMwjZzM,4278
+bulkurlchecker-0.1.0.dist-info/licenses/LICENSE,sha256=R9-95i5U2iwohiXs4napv1aiu1nAd3tRvW3geDL8Ky4,1073
+bulkurlchecker-0.1.0.dist-info/METADATA,sha256=30xYsMRMOs_LXkM2WM3XeGOQqCl610HYZI45P9HNv-A,7438
+bulkurlchecker-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+bulkurlchecker-0.1.0.dist-info/top_level.txt,sha256=ApFhZQ33R6RdOCXCplNtbor2M2VffWUdDxv5okxSM3Y,15
+bulkurlchecker-0.1.0.dist-info/RECORD,,

bulkurlchecker-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bulkurlchecker-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bulk URL Checker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bulkurlchecker-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+bulkurlchecker