pdftagger 0.1.0__py3-none-any.whl

pdftagger/__init__.py

@@ -0,0 +1,65 @@
+"""Official Python SDK for the PDF Tagger API.
+
+Auto-tag PDFs for PDF/UA accessibility from your own code:
+
+    >>> from pdftagger import PdfTaggerClient
+    >>> client = PdfTaggerClient(api_key="sk_live_...")
+    >>> job = client.tag_pdf("report.pdf", ocr=True)
+    >>> client.download_result(job, "report.tagged.pdf")
+
+Many PDFs at once, as one batch:
+
+    >>> batch = client.tag_pdfs(["a.pdf", "b.pdf", "c.pdf"])
+    >>> client.download_batch_results(batch, "tagged/")
+"""
+
+from __future__ import annotations
+
+from ._version import __version__
+from .client import DEFAULT_BASE_URL, PdfTaggerClient
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    InsufficientCreditsError,
+    JobFailed,
+    JobTimeout,
+    NotFoundError,
+    PdfTaggerError,
+    RateLimitError,
+    WebhookVerificationError,
+)
+from .models import Account, Batch, BatchCounts, BatchEvent, BatchItem, Job, JobResult, Upload, WebhookEvent
+from .webhooks import SIGNATURE_HEADER, verify_signature
+
+__all__ = [
+    "__version__",
+    "PdfTaggerClient",
+    "DEFAULT_BASE_URL",
+    # models
+    "Account",
+    "Upload",
+    "Job",
+    "JobResult",
+    "Batch",
+    "BatchItem",
+    "BatchCounts",
+    "BatchEvent",
+    "WebhookEvent",
+    # webhooks
+    "verify_signature",
+    "SIGNATURE_HEADER",
+    # exceptions
+    "PdfTaggerError",
+    "APIError",
+    "BadRequestError",
+    "AuthenticationError",
+    "InsufficientCreditsError",
+    "NotFoundError",
+    "ConflictError",
+    "RateLimitError",
+    "JobTimeout",
+    "JobFailed",
+    "WebhookVerificationError",
+]

pdftagger/_version.py

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

pdftagger/client.py

@@ -0,0 +1,483 @@
+"""The synchronous PDF Tagger API client."""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Any, BinaryIO, Dict, List, Optional, Sequence, Union
+
+import httpx
+
+from ._version import __version__
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    InsufficientCreditsError,
+    JobFailed,
+    JobTimeout,
+    NotFoundError,
+    RateLimitError,
+)
+from .models import Account, Batch, BatchItem, BatchItemInput, Job, JobResult, Upload
+
+DEFAULT_BASE_URL = "https://api.pdf-tagger.com"
+
+#: Seconds to wait for ``POST /v1/batches``. The API reads every file before it answers, so a
+#: batch takes longer to accept than one job.
+BATCH_SUBMIT_TIMEOUT = 300.0
+
+# status code -> exception class (429 is handled separately to read Retry-After)
+_ERROR_BY_STATUS = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    402: InsufficientCreditsError,
+    404: NotFoundError,
+    409: ConflictError,
+}
+
+FileInput = Union[str, Path, BinaryIO]
+
+
+class PdfTaggerClient:
+    """A client for the PDF Tagger API.
+
+    Args:
+        api_key: Your API key (``sk_live_…``).
+        base_url: Override the API base URL (for testing or a private deployment).
+        timeout: Per-request timeout in seconds.
+        http_client: Supply your own ``httpx.Client`` (its lifecycle is then yours).
+
+    Example:
+        >>> from pdftagger import PdfTaggerClient
+        >>> with PdfTaggerClient(api_key="sk_live_...") as client:
+        ...     job = client.tag_pdf("report.pdf", ocr=True)
+        ...     client.download_result(job, "report.tagged.pdf")
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.Client(timeout=timeout)
+
+    # -- lifecycle ---------------------------------------------------------------
+
+    def __enter__(self) -> "PdfTaggerClient":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying HTTP client (only if the SDK created it)."""
+        if self._owns_client:
+            self._http.close()
+
+    # -- low-level request plumbing ---------------------------------------------
+
+    def _auth_headers(self, extra: Optional[Dict[str, str]] = None) -> Dict[str, str]:
+        headers = {
+            "Authorization": f"Bearer {self._api_key}",
+            "User-Agent": f"pdftagger-python/{__version__}",
+            "Accept": "application/json",
+        }
+        if extra:
+            headers.update(extra)
+        return headers
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        timeout: Optional[float] = None,
+    ) -> Dict[str, Any]:
+        url = f"{self._base_url}{path}"
+        extra: Dict[str, Any] = {"timeout": timeout} if timeout is not None else {}
+        try:
+            response = self._http.request(method, url, json=json, headers=self._auth_headers(headers), **extra)
+        except httpx.HTTPError as exc:
+            raise APIError(f"HTTP request to {path} failed: {exc}") from exc
+        return self._handle_response(response)
+
+    def _handle_response(self, response: httpx.Response) -> Dict[str, Any]:
+        request_id = response.headers.get("X-Request-Id")
+
+        if response.is_success:
+            if response.status_code == 204 or not response.content:
+                return {}
+            try:
+                return response.json()
+            except ValueError:
+                return {}
+
+        error_type: Optional[str] = None
+        message: Optional[str] = None
+        job_errors: List[Dict[str, Any]] = []
+        try:
+            body = response.json()
+            error = body.get("error") or {}
+            error_type = error.get("type")
+            message = error.get("message")
+            request_id = error.get("request_id") or request_id
+            job_errors = list(error.get("errors") or [])
+        except ValueError:
+            message = response.text or None
+
+        message = message or f"HTTP {response.status_code}"
+        common = {
+            "status_code": response.status_code,
+            "type": error_type,
+            "request_id": request_id,
+            "errors": job_errors,
+        }
+
+        if response.status_code == 429:
+            raw_retry = response.headers.get("Retry-After")
+            retry_after = int(raw_retry) if raw_retry and raw_retry.isdigit() else None
+            raise RateLimitError(message, retry_after=retry_after, **common)
+
+        error_cls = _ERROR_BY_STATUS.get(response.status_code, APIError)
+        raise error_cls(message, **common)
+
+    # -- endpoints (1:1 with the API) -------------------------------------------
+
+    def get_account(self) -> Account:
+        """Return the authenticated account and its credit balance."""
+        return Account.from_dict(self._request("GET", "/v1/me"))
+
+    def create_upload(self, filename: Optional[str] = None) -> Upload:
+        """Create a presigned upload target. Follow with :meth:`upload_file`."""
+        payload: Dict[str, Any] = {}
+        if filename:
+            payload["filename"] = filename
+        return Upload.from_dict(self._request("POST", "/v1/uploads", json=payload))
+
+    def upload_file(self, upload: Upload, file: FileInput) -> None:
+        """Upload the PDF bytes to the presigned target from :meth:`create_upload`.
+
+        The presigned POST requires every field from ``upload.fields`` to precede the
+        file part, which this method guarantees.
+        """
+        fh: BinaryIO
+        should_close = False
+        if isinstance(file, (str, Path)):
+            fh = open(file, "rb")
+            should_close = True
+            filename = Path(file).name
+        else:
+            fh = file
+            filename = getattr(file, "name", None) or "document.pdf"
+            filename = Path(str(filename)).name
+
+        try:
+            # httpx serializes `data` (the presigned fields) before `files`, so the file
+            # part comes last — which is what S3 requires.
+            files = {"file": (filename, fh, "application/pdf")}
+            response = self._http.post(upload.upload_url, data=dict(upload.fields), files=files)
+        except httpx.HTTPError as exc:
+            raise APIError(f"Upload to storage failed: {exc}") from exc
+        finally:
+            if should_close:
+                fh.close()
+
+        if not response.is_success:
+            raise APIError(
+                f"Upload to storage failed: HTTP {response.status_code}",
+                status_code=response.status_code,
+            )
+
+    def submit_job(
+        self,
+        *,
+        key: str,
+        ocr: bool = False,
+        embed_fonts: bool = False,
+        filename: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Job:
+        """Submit a tagging job for an uploaded ``key``. Charges one credit per page."""
+        options: Dict[str, bool] = {}
+        if ocr:
+            options["ocr"] = True
+        if embed_fonts:
+            options["embed_fonts"] = True
+
+        payload: Dict[str, Any] = {"key": key}
+        if filename:
+            payload["filename"] = filename
+        if options:
+            payload["options"] = options
+
+        headers: Dict[str, str] = {}
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+
+        return Job.from_dict(self._request("POST", "/v1/jobs", json=payload, headers=headers))
+
+    def get_job(self, job: Union[str, Job]) -> Job:
+        """Fetch a job's current status."""
+        return Job.from_dict(self._request("GET", f"/v1/jobs/{_job_id(job)}"))
+
+    def get_job_result(self, job: Union[str, Job]) -> JobResult:
+        """Get a short-lived download URL for a completed job."""
+        return JobResult.from_dict(self._request("GET", f"/v1/jobs/{_job_id(job)}/result"))
+
+    def submit_batch(
+        self,
+        items: Sequence[BatchItemInput],
+        *,
+        name: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+        timeout: float = BATCH_SUBMIT_TIMEOUT,
+    ) -> Batch:
+        """Submit 1 to 100 uploaded files as one batch. Charges one credit per page.
+
+        Each item is an upload ``key`` or a :class:`~pdftagger.models.BatchItem` (to set a
+        filename or options). All or nothing: if any job is bad, this raises
+        :class:`~pdftagger.exceptions.BadRequestError` with one entry in ``errors`` for each
+        bad job, and nothing is charged; too few credits raises
+        :class:`~pdftagger.exceptions.InsufficientCreditsError`.
+        """
+        jobs = [BatchItem(key=i) if isinstance(i, str) else i for i in items]
+        payload: Dict[str, Any] = {"jobs": [j.to_payload() for j in jobs]}
+        if name:
+            payload["name"] = name
+        headers: Dict[str, str] = {}
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        return Batch.from_dict(
+            self._request("POST", "/v1/batches", json=payload, headers=headers, timeout=timeout)
+        )
+
+    def get_batch(self, batch: Union[str, Batch]) -> Batch:
+        """Fetch a batch's status, counts and jobs."""
+        return Batch.from_dict(self._request("GET", f"/v1/batches/{_batch_id(batch)}"))
+
+    # -- high-level helpers ------------------------------------------------------
+
+    def tag_pdf(
+        self,
+        file: FileInput,
+        *,
+        ocr: bool = False,
+        embed_fonts: bool = False,
+        filename: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+        wait: bool = True,
+        poll_interval: float = 3.0,
+        poll_timeout: Optional[float] = None,
+    ) -> Job:
+        """Upload, submit, and (by default) wait for a PDF to be tagged.
+
+        Args:
+            file: A path or open binary file for the PDF to tag.
+            ocr: Force OCR on image-only pages.
+            embed_fonts: Embed a non-embedded font where safe.
+            filename: Name to record for the job (defaults to the file's name).
+            idempotency_key: Make the submit safe to retry without double-charging.
+            wait: If True, poll until the job finishes; if False, return the accepted job.
+            poll_interval: Seconds between status checks while waiting.
+            poll_timeout: Give up waiting after this many seconds. The default (``None``)
+                waits until the job is terminal — the service guarantees a job reaches
+                ``completed`` or ``failed`` within 24 hours. Set a bound if you need one.
+
+        Returns:
+            The :class:`~pdftagger.models.Job` — completed when ``wait`` is True.
+
+        Raises:
+            JobFailed: The job finished with a ``failed`` status.
+            JobTimeout: ``wait`` is True and the job did not finish within ``poll_timeout``.
+        """
+        default_name = Path(file).name if isinstance(file, (str, Path)) else None
+        upload = self.create_upload(filename=filename or default_name)
+        self.upload_file(upload, file)
+        job = self.submit_job(
+            key=upload.key,
+            ocr=ocr,
+            embed_fonts=embed_fonts,
+            filename=filename or default_name,
+            idempotency_key=idempotency_key,
+        )
+        if not wait:
+            return job
+        return self.wait_for_job(job, poll_interval=poll_interval, poll_timeout=poll_timeout)
+
+    def wait_for_job(
+        self,
+        job: Union[str, Job],
+        *,
+        poll_interval: float = 3.0,
+        poll_timeout: Optional[float] = None,
+    ) -> Job:
+        """Poll a job until it is completed, raising on failure or timeout.
+
+        ``poll_timeout=None`` (the default) waits until the job is terminal; the service
+        guarantees that within 24 hours.
+        """
+        job_id = _job_id(job)
+        deadline = time.monotonic() + poll_timeout if poll_timeout is not None else None
+
+        while True:
+            try:
+                current = self.get_job(job_id)
+            except RateLimitError as exc:
+                time.sleep(exc.retry_after or poll_interval)
+                continue
+
+            if current.is_terminal:
+                if current.status == "failed":
+                    raise JobFailed(f"Job {current.id} failed", job=current)
+                return current
+
+            if deadline is not None and time.monotonic() >= deadline:
+                raise JobTimeout(
+                    f"Job {job_id} did not finish within {poll_timeout}s", job=current
+                )
+
+            time.sleep(poll_interval)
+
+    def tag_pdfs(
+        self,
+        files: Sequence[FileInput],
+        *,
+        name: Optional[str] = None,
+        ocr: bool = False,
+        embed_fonts: bool = False,
+        idempotency_key: Optional[str] = None,
+        wait: bool = True,
+        poll_interval: float = 5.0,
+        poll_timeout: Optional[float] = None,
+    ) -> Batch:
+        """Upload many PDFs, submit them as one batch, and (by default) wait for all of them.
+
+        Unlike :meth:`tag_pdf`, a failed job does not raise: a batch can finish with some
+        jobs completed and some failed. Check :attr:`Batch.failed_jobs`, then save the rest
+        with :meth:`download_batch_results`.
+
+        Args:
+            files: 1 to 100 paths or open binary files.
+            name: A name for the batch (the API picks one if omitted).
+            ocr: Force OCR on image-only pages, for every file.
+            embed_fonts: Embed a non-embedded font where safe, for every file.
+            idempotency_key: Make the submit safe to retry without double-charging.
+            wait: If True, poll until every job has finished.
+            poll_interval: Seconds between status checks while waiting.
+            poll_timeout: Give up waiting after this many seconds (``None`` waits until done).
+        """
+        items: List[BatchItem] = []
+        for file in files:
+            filename = Path(file).name if isinstance(file, (str, Path)) else None
+            upload = self.create_upload(filename=filename)
+            self.upload_file(upload, file)
+            items.append(BatchItem(key=upload.key, filename=filename, ocr=ocr, embed_fonts=embed_fonts))
+        batch = self.submit_batch(items, name=name, idempotency_key=idempotency_key)
+        if not wait:
+            return batch
+        return self.wait_for_batch(batch, poll_interval=poll_interval, poll_timeout=poll_timeout)
+
+    def wait_for_batch(
+        self,
+        batch: Union[str, Batch],
+        *,
+        poll_interval: float = 5.0,
+        poll_timeout: Optional[float] = None,
+    ) -> Batch:
+        """Poll a batch until every job has finished. Failed jobs do not raise.
+
+        Raises:
+            JobTimeout: The batch did not finish within ``poll_timeout`` seconds.
+        """
+        batch_id = _batch_id(batch)
+        deadline = time.monotonic() + poll_timeout if poll_timeout is not None else None
+        while True:
+            try:
+                current = self.get_batch(batch_id)
+            except RateLimitError as exc:
+                time.sleep(exc.retry_after or poll_interval)
+                continue
+            if current.is_terminal:
+                return current
+            if deadline is not None and time.monotonic() >= deadline:
+                raise JobTimeout(f"Batch {batch_id} did not finish within {poll_timeout}s")
+            time.sleep(poll_interval)
+
+    def download_batch_results(self, batch: Union[str, Batch], dest_dir: Union[str, Path]) -> List[Path]:
+        """Save every completed job's tagged PDF in ``dest_dir`` and return the paths.
+
+        Files keep their uploaded names; a repeated name gets a number (``report (2).pdf``).
+        Failed jobs are skipped.
+        """
+        current = batch if isinstance(batch, Batch) else self.get_batch(batch)
+        folder = Path(dest_dir)
+        folder.mkdir(parents=True, exist_ok=True)
+        names = _unique_names([j.filename or f"{j.id}.pdf" for j in current.completed_jobs])
+        return [
+            self.download_result(job, folder / filename)  # type: ignore[misc]
+            for job, filename in zip(current.completed_jobs, names)
+        ]
+
+    def download_result(
+        self,
+        job: Union[str, Job],
+        dest: Optional[Union[str, Path]] = None,
+    ) -> Union[bytes, Path]:
+        """Download a completed job's tagged PDF.
+
+        Returns the written :class:`~pathlib.Path` when ``dest`` is given, otherwise the
+        PDF bytes.
+        """
+        result = self.get_job_result(job)
+        try:
+            response = self._http.get(result.result_url)
+        except httpx.HTTPError as exc:
+            raise APIError(f"Download failed: {exc}") from exc
+        if not response.is_success:
+            raise APIError(
+                f"Download failed: HTTP {response.status_code}", status_code=response.status_code
+            )
+
+        if dest is None:
+            return response.content
+        path = Path(dest)
+        path.write_bytes(response.content)
+        return path
+
+
+def _job_id(job: Union[str, Job]) -> str:
+    return job.id if isinstance(job, Job) else job
+
+
+def _batch_id(batch: Union[str, Batch]) -> str:
+    return batch.id if isinstance(batch, Batch) else batch
+
+
+def _unique_names(names: List[str]) -> List[str]:
+    """Make file names unique, so two jobs with one name do not overwrite each other."""
+    used = set()
+    out = []
+    for raw in names:
+        name = Path(raw.replace("\\", "_")).name or "document.pdf"
+        stem, dot, ext = name.rpartition(".")
+        if not dot:
+            stem, ext = name, "pdf"
+        candidate, n = name, 2
+        while candidate.lower() in used:
+            candidate = f"{stem} ({n}).{ext}"
+            n += 1
+        used.add(candidate.lower())
+        out.append(candidate)
+    return out

pdftagger/exceptions.py

@@ -0,0 +1,107 @@
+"""Exception hierarchy for the PDF Tagger SDK.
+
+Every error the SDK raises derives from :class:`PdfTaggerError`, so a caller can catch
+that one type to handle anything the SDK can throw. API responses map to a specific
+subclass of :class:`APIError` by status code.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+if TYPE_CHECKING:  # avoid a runtime import cycle (models imports nothing from here)
+    from .models import Job
+
+
+class PdfTaggerError(Exception):
+    """Base class for every error raised by the SDK."""
+
+
+class APIError(PdfTaggerError):
+    """An error returned by the API, or an unexpected HTTP/transport failure.
+
+    Attributes:
+        status_code: The HTTP status code, when the failure came from a response.
+        type: The API error ``type`` string, when the body carried one.
+        request_id: The request id for support, from the body or the ``X-Request-Id`` header.
+        errors: On a refused batch (``POST /v1/batches``), one entry for each bad job:
+            ``{"index": <place in jobs, from 0>, "type": ..., "message": ...}``. Otherwise empty.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        type: Optional[str] = None,
+        request_id: Optional[str] = None,
+        errors: Optional[List[Dict[str, Any]]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.type = type
+        self.request_id = request_id
+        self.errors: List[Dict[str, Any]] = list(errors or [])
+
+
+class BadRequestError(APIError):
+    """HTTP 400 — the request was invalid."""
+
+
+class AuthenticationError(APIError):
+    """HTTP 401 — the API key is missing, invalid, or revoked."""
+
+
+class InsufficientCreditsError(APIError):
+    """HTTP 402 — the account does not have enough credits for the job."""
+
+
+class NotFoundError(APIError):
+    """HTTP 404 — no such resource for this account."""
+
+
+class ConflictError(APIError):
+    """HTTP 409 — an idempotency conflict, or a resource not ready yet."""
+
+
+class RateLimitError(APIError):
+    """HTTP 429 — the rate limit was exceeded.
+
+    Attributes:
+        retry_after: Seconds to wait before retrying, from the ``Retry-After`` header.
+    """
+
+    def __init__(self, message: str, *, retry_after: Optional[int] = None, **kwargs) -> None:
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class JobTimeout(PdfTaggerError):
+    """A job did not reach a terminal state within the poll timeout.
+
+    Attributes:
+        job: The last :class:`~pdftagger.models.Job` observed, if any.
+    """
+
+    def __init__(self, message: str, *, job: "Optional[Job]" = None) -> None:
+        super().__init__(message)
+        self.job = job
+
+
+class JobFailed(PdfTaggerError):
+    """A job reached a terminal ``failed`` status while waiting for it.
+
+    Credits for a failed job are refunded automatically by the service.
+
+    Attributes:
+        job: The failed :class:`~pdftagger.models.Job`.
+    """
+
+    def __init__(self, message: str, *, job: "Optional[Job]" = None) -> None:
+        super().__init__(message)
+        self.job = job
+
+
+class WebhookVerificationError(PdfTaggerError):
+    """A webhook signature could not be verified (bad signature, format, or replay)."""

pdftagger/models.py

@@ -0,0 +1,282 @@
+"""Typed data models returned by the SDK.
+
+Each model keeps the full server payload in ``raw`` so a new API field is always
+reachable even before the SDK adds a typed attribute for it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Mapping, Optional, Union
+
+# Terminal job statuses (the job will not change again).
+COMPLETED = "completed"
+FAILED = "failed"
+PROCESSING = "processing"
+TERMINAL_STATUSES = (COMPLETED, FAILED)
+
+
+@dataclass
+class Account:
+    """The authenticated account and its credit balance (``GET /v1/me``)."""
+
+    account_id: Optional[str] = None
+    plan: Optional[str] = None
+    subscription_status: Optional[str] = None
+    credits_available: Optional[int] = None
+    request_id: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> "Account":
+        return cls(
+            account_id=data.get("account_id"),
+            plan=data.get("plan"),
+            subscription_status=data.get("subscription_status"),
+            credits_available=data.get("credits_available"),
+            request_id=data.get("request_id"),
+            raw=dict(data),
+        )
+
+
+@dataclass
+class Upload:
+    """A presigned upload target (``POST /v1/uploads``).
+
+    Pass ``key`` to :meth:`~pdftagger.client.PdfTaggerClient.submit_job` after the file
+    has been uploaded to ``upload_url`` with every entry in ``fields``.
+    """
+
+    upload_url: str
+    fields: Dict[str, str]
+    key: str
+    request_id: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> "Upload":
+        return cls(
+            upload_url=data["upload_url"],
+            fields=dict(data.get("fields") or {}),
+            key=data["key"],
+            request_id=data.get("request_id"),
+            raw=dict(data),
+        )
+
+
+@dataclass
+class Job:
+    """A tagging job (``POST /v1/jobs`` and ``GET /v1/jobs/{id}``)."""
+
+    id: str
+    status: str
+    filename: Optional[str] = None
+    credits_used: Optional[int] = None
+    options: Optional[Dict[str, Any]] = None
+    created_at: Optional[str] = None
+    request_id: Optional[str] = None
+    #: Why the job failed. Set on the jobs inside a :class:`Batch` and in job webhook events.
+    error_code: Optional[str] = None
+    error_message: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> "Job":
+        return cls(
+            id=data["id"],
+            status=data["status"],
+            filename=data.get("filename"),
+            credits_used=data.get("credits_used"),
+            options=data.get("options"),
+            created_at=data.get("created_at"),
+            request_id=data.get("request_id"),
+            error_code=data.get("error_code"),
+            error_message=data.get("error_message"),
+            raw=dict(data),
+        )
+
+    @property
+    def is_terminal(self) -> bool:
+        """True once the job is ``completed`` or ``failed``."""
+        return self.status in TERMINAL_STATUSES
+
+    @property
+    def succeeded(self) -> bool:
+        """True only when the job is ``completed``."""
+        return self.status == COMPLETED
+
+
+@dataclass
+class JobResult:
+    """A short-lived download link for a finished job (``GET /v1/jobs/{id}/result``)."""
+
+    result_url: str
+    expires_in: Optional[int] = None
+    request_id: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> "JobResult":
+        return cls(
+            result_url=data["result_url"],
+            expires_in=data.get("expires_in"),
+            request_id=data.get("request_id"),
+            raw=dict(data),
+        )
+
+
+@dataclass
+class BatchItem:
+    """One file in a batch for :meth:`~pdftagger.client.PdfTaggerClient.submit_batch`.
+
+    ``key`` comes from :meth:`~pdftagger.client.PdfTaggerClient.create_upload`.
+    """
+
+    key: str
+    filename: Optional[str] = None
+    ocr: bool = False
+    embed_fonts: bool = False
+
+    def to_payload(self) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"key": self.key}
+        if self.filename:
+            payload["filename"] = self.filename
+        options: Dict[str, bool] = {}
+        if self.ocr:
+            options["ocr"] = True
+        if self.embed_fonts:
+            options["embed_fonts"] = True
+        if options:
+            payload["options"] = options
+        return payload
+
+
+@dataclass
+class BatchCounts:
+    """How many jobs in a batch are in each status."""
+
+    total: int = 0
+    processing: int = 0
+    completed: int = 0
+    failed: int = 0
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> "BatchCounts":
+        return cls(
+            total=data.get("total", 0),
+            processing=data.get("processing", 0),
+            completed=data.get("completed", 0),
+            failed=data.get("failed", 0),
+        )
+
+
+@dataclass
+class Batch:
+    """A batch of jobs (``POST /v1/batches`` and ``GET /v1/batches/{id}``).
+
+    ``status`` is ``completed`` once every job has finished, whether each job completed
+    or failed. ``jobs`` keeps the order of the request.
+    """
+
+    id: str
+    status: str
+    name: Optional[str] = None
+    counts: BatchCounts = field(default_factory=BatchCounts)
+    credits_used: Optional[int] = None
+    created_at: Optional[str] = None
+    completed_at: Optional[str] = None
+    jobs: List[Job] = field(default_factory=list)
+    request_id: Optional[str] = None
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> "Batch":
+        return cls(
+            id=data["id"],
+            status=data["status"],
+            name=data.get("name"),
+            counts=BatchCounts.from_dict(data.get("counts") or {}),
+            credits_used=data.get("credits_used"),
+            created_at=data.get("created_at"),
+            completed_at=data.get("completed_at"),
+            jobs=[Job.from_dict(j) for j in data.get("jobs") or []],
+            request_id=data.get("request_id"),
+            raw=dict(data),
+        )
+
+    @property
+    def is_terminal(self) -> bool:
+        """True once every job in the batch has finished."""
+        return self.status == COMPLETED
+
+    @property
+    def completed_jobs(self) -> List[Job]:
+        """The jobs whose tagged PDF is ready to download."""
+        return [j for j in self.jobs if j.status == COMPLETED]
+
+    @property
+    def failed_jobs(self) -> List[Job]:
+        """The jobs that failed. Their credits are refunded."""
+        return [j for j in self.jobs if j.status == FAILED]
+
+
+@dataclass
+class BatchEvent:
+    """The batch data in a ``batch.completed`` webhook event."""
+
+    id: str
+    name: Optional[str] = None
+    status: Optional[str] = None
+    total: int = 0
+    completed: int = 0
+    failed: int = 0
+    created_at: Optional[str] = None
+    completed_at: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> "BatchEvent":
+        return cls(
+            id=data["id"],
+            name=data.get("name"),
+            status=data.get("status"),
+            total=data.get("total", 0),
+            completed=data.get("completed", 0),
+            failed=data.get("failed", 0),
+            created_at=data.get("created_at"),
+            completed_at=data.get("completed_at"),
+        )
+
+
+@dataclass
+class WebhookEvent:
+    """A verified webhook event: ``job.completed``, ``job.failed`` or ``batch.completed``.
+
+    A job event sets ``job``; a ``batch.completed`` event sets ``batch``. The event carries
+    no result URL — fetch it with
+    :meth:`~pdftagger.client.PdfTaggerClient.get_job_result`, or read a batch's jobs with
+    :meth:`~pdftagger.client.PdfTaggerClient.get_batch`.
+    """
+
+    id: Optional[str]
+    type: str
+    created: Optional[int]
+    job: Optional[Job]
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+    batch: Optional[BatchEvent] = None
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any]) -> "WebhookEvent":
+        body = data.get("data") or {}
+        job_data = body.get("job")
+        batch_data = body.get("batch")
+        return cls(
+            id=data.get("id"),
+            type=data.get("type", ""),
+            created=data.get("created"),
+            job=Job.from_dict(job_data) if job_data else None,
+            raw=dict(data),
+            batch=BatchEvent.from_dict(batch_data) if batch_data else None,
+        )
+
+
+BatchItemInput = Union[str, BatchItem]

pdftagger/webhooks.py

@@ -0,0 +1,97 @@
+"""Verify PDF Tagger webhook deliveries.
+
+Every delivery carries an ``X-PDFTagger-Signature`` header of the form
+``t=<unixSeconds>,v1=<hex-hmac>``, where the HMAC is SHA-256 over ``"<t>.<rawBody>"``
+keyed by the endpoint secret (``whsec_…``). :func:`verify_signature` recomputes the HMAC
+over the exact bytes you received, compares it in constant time, and rejects a stale
+timestamp (replay). This mirrors the server's ``signWebhook`` implementation.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Dict, Optional, Union
+
+from .exceptions import WebhookVerificationError
+from .models import WebhookEvent
+
+#: Header the server sends the signature in.
+SIGNATURE_HEADER = "X-PDFTagger-Signature"
+#: Default replay window, in seconds.
+DEFAULT_TOLERANCE_SECONDS = 300
+
+
+def _parse_signature_header(header: str) -> Dict[str, str]:
+    parts: Dict[str, str] = {}
+    for item in header.split(","):
+        item = item.strip()
+        if "=" in item:
+            key, value = item.split("=", 1)
+            parts[key.strip()] = value.strip()
+    return parts
+
+
+def verify_signature(
+    payload: Union[bytes, bytearray, str],
+    header: Optional[str],
+    secret: str,
+    *,
+    tolerance: Optional[int] = DEFAULT_TOLERANCE_SECONDS,
+    now: Optional[int] = None,
+) -> WebhookEvent:
+    """Verify a webhook signature and return the parsed event.
+
+    Args:
+        payload: The **raw** request body, exactly as received (bytes are preferred; a
+            str is encoded as UTF-8). Do not re-serialize a parsed JSON object — a
+            different byte layout will not match the signature.
+        header: The ``X-PDFTagger-Signature`` header value.
+        secret: The endpoint signing secret (``whsec_…``).
+        tolerance: Max allowed difference between the signed timestamp and now, in
+            seconds. Pass ``None`` to skip the replay check.
+        now: Current unix time, for testing. Defaults to :func:`time.time`.
+
+    Returns:
+        The verified :class:`~pdftagger.models.WebhookEvent`.
+
+    Raises:
+        WebhookVerificationError: If the header is missing or malformed, the signature
+            does not match, the timestamp is outside ``tolerance``, or the body is not
+            valid JSON.
+    """
+    payload_bytes = payload.encode("utf-8") if isinstance(payload, str) else bytes(payload)
+
+    if not header:
+        raise WebhookVerificationError("Missing signature header")
+
+    parts = _parse_signature_header(header)
+    timestamp = parts.get("t")
+    provided = parts.get("v1")
+    if not timestamp or not provided:
+        raise WebhookVerificationError("Malformed signature header")
+
+    try:
+        timestamp_int = int(timestamp)
+    except ValueError as exc:
+        raise WebhookVerificationError("Invalid timestamp in signature header") from exc
+
+    signed = f"{timestamp_int}.".encode("utf-8") + payload_bytes
+    expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
+
+    if not hmac.compare_digest(expected, provided):
+        raise WebhookVerificationError("Signature mismatch")
+
+    if tolerance is not None:
+        current = int(now if now is not None else time.time())
+        if abs(current - timestamp_int) > tolerance:
+            raise WebhookVerificationError("Timestamp outside tolerance (possible replay)")
+
+    try:
+        data = json.loads(payload_bytes.decode("utf-8"))
+    except ValueError as exc:
+        raise WebhookVerificationError(f"Payload is not valid JSON: {exc}") from exc
+
+    return WebhookEvent.from_dict(data)

pdftagger-0.1.0.dist-info/METADATA

@@ -0,0 +1,202 @@
+Metadata-Version: 2.5
+Name: pdftagger
+Version: 0.1.0
+Summary: Official Python SDK for the PDF Tagger API — auto-tag PDFs for PDF/UA accessibility.
+Project-URL: Homepage, https://pdf-tagger.com
+Project-URL: Documentation, https://pdf-tagger.com/api/reference
+Project-URL: Source, https://github.com/rachel-ackeret/pdftagger-python
+Project-URL: Issues, https://github.com/rachel-ackeret/pdftagger-python/issues
+Author: PDF Tagger
+License: MIT License
+        
+        Copyright (c) 2026 PDF Tagger
+        
+        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.
+License-File: LICENSE
+Keywords: accessibility,auto-tag,pdf,pdf-ua,pdf/ua,sdk,section-508,tagging,wcag
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: respx>=0.20; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pdftagger — auto-tag PDFs for accessibility from Python
+
+Official Python SDK for the [PDF Tagger](https://pdf-tagger.com) API. Upload a PDF,
+submit a tagging job, and download a **PDF/UA-tagged, accessible** PDF — with correct
+reading order, headings, tables, and alt text. Tag one PDF, or up to 100 at once as a batch.
+
+```bash
+pip install pdftagger
+```
+
+## How to auto-tag PDFs with the PDF Tagger SDK
+
+Get an API key from the [Developers page](https://pdf-tagger.com/developers), then:
+
+```python
+from pdftagger import PdfTaggerClient
+
+client = PdfTaggerClient(api_key="sk_live_...")
+
+# Upload, submit, and wait for the tagged PDF — one call.
+job = client.tag_pdf("report.pdf", ocr=True)
+
+# Save the accessible, tagged PDF.
+client.download_result(job, "report.tagged.pdf")
+```
+
+That's the whole flow. `tag_pdf()` uploads the file, submits the job, polls until it
+finishes, and returns the completed job. Each job costs one credit per page, drawn from
+the same balance as the web app.
+
+### Options
+
+```python
+job = client.tag_pdf(
+    "scan.pdf",
+    ocr=True,            # recover text from image-only / scanned pages
+    embed_fonts=True,    # embed a non-embedded font where it is safe to do so
+    idempotency_key="order-1234",  # safe to retry without double-charging
+)
+```
+
+Don't want to block? Submit and poll yourself:
+
+```python
+job = client.tag_pdf("report.pdf", wait=False)   # returns immediately
+job = client.wait_for_job(job)                    # ...poll later
+```
+
+## Many PDFs at once: batches
+
+Tag up to 100 PDFs as one batch. `tag_pdfs()` uploads every file, submits them in one
+request, and waits until every job has finished:
+
+```python
+batch = client.tag_pdfs(["a.pdf", "b.pdf", "c.pdf"], name="Q3 reports", ocr=True)
+
+print(batch.counts)                 # BatchCounts(total=3, processing=0, completed=3, failed=0)
+for job in batch.failed_jobs:       # a failed job does not raise for a batch
+    print(job.filename, job.error_code, job.error_message)
+
+client.download_batch_results(batch, "tagged/")   # saves each completed PDF
+```
+
+A batch is **all or nothing**: if any file is not a PDF, has more than 750 pages, or the
+credits do not cover every page, nothing is charged and the call raises.
+`BadRequestError.errors` lists each bad file by its position:
+
+```python
+from pdftagger import BadRequestError
+
+try:
+    client.submit_batch([upload_a.key, upload_b.key])
+except BadRequestError as e:
+    for problem in e.errors:        # {"index": 1, "type": "too_many_pages", "message": "..."}
+        print(problem["index"], problem["message"])
+```
+
+Drive it yourself with `submit_batch()` (upload keys or `BatchItem`s), `get_batch()` and
+`wait_for_batch()`. Each job in a batch is a normal job, so `get_job()`,
+`get_job_result()` and `download_result()` work on it.
+
+## Verifying webhooks
+
+Register a webhook endpoint on the Developers page to be notified when a job finishes.
+Verify every delivery before trusting it — pass the **raw** request body:
+
+```python
+from pdftagger import verify_signature
+from pdftagger.webhooks import SIGNATURE_HEADER
+
+event = verify_signature(
+    payload=raw_body_bytes,                 # the exact bytes you received
+    header=request.headers[SIGNATURE_HEADER],
+    secret="whsec_...",                     # the endpoint secret
+)
+
+if event.type == "job.completed":
+    url = client.get_job_result(event.job.id).result_url
+elif event.type == "batch.completed":
+    batch = client.get_batch(event.batch.id)    # every job in the batch has finished
+```
+
+`verify_signature` recomputes the HMAC-SHA256 signature over the raw body, compares it in
+constant time, and rejects a stale timestamp (replay). It raises
+`WebhookVerificationError` on any failure. A delivery can arrive more than once, so
+dedupe on `event.id`.
+
+## Low-level API
+
+Every endpoint is available directly if you want to drive the flow yourself:
+
+```python
+client.get_account()                       # account + credit balance
+upload = client.create_upload("report.pdf")
+client.upload_file(upload, "report.pdf")
+job = client.submit_job(key=upload.key, ocr=True)
+job = client.get_job(job.id)               # processing / completed / failed
+result = client.get_job_result(job.id)     # short-lived download URL
+```
+
+## Errors
+
+All errors derive from `PdfTaggerError`.
+
+| Exception | When |
+|---|---|
+| `AuthenticationError` | 401 — key missing, invalid, or revoked |
+| `BadRequestError` | 400 — invalid request (for a batch, `.errors` lists each bad file) |
+| `InsufficientCreditsError` | 402 — not enough credits (a batch charges nothing) |
+| `NotFoundError` | 404 — no such job/resource for this account |
+| `ConflictError` | 409 — idempotency conflict, or result not ready |
+| `RateLimitError` | 429 — rate limited (`.retry_after` seconds) |
+| `JobFailed` | the job finished with a `failed` status (credits are refunded) |
+| `JobTimeout` | the job, or the batch, did not finish within the poll timeout |
+| `WebhookVerificationError` | a webhook signature could not be verified |
+
+## Requirements
+
+- Python 3.9+
+- [`httpx`](https://www.python-httpx.org/) (installed automatically)
+
+## Links
+
+- API reference: https://pdf-tagger.com/api/reference
+- Create an API key: https://pdf-tagger.com/developers
+
+## License
+
+MIT

pdftagger-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pdftagger/__init__.py,sha256=16gtKU5MizUa3-YEMbaMp3EmT3l7xe1Kx6D8yByF-QQ,1593
+pdftagger/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+pdftagger/client.py,sha256=vDX9B7EYOmdvm7I9YO0xXt23DEEbdnR66xeZwGqF52w,18246
+pdftagger/exceptions.py,sha256=7s3LwoG4151-O4On_oIjpABtXAYeYsgsXwHqC6heEoE,3384
+pdftagger/models.py,sha256=VpYwvUvmaXal1BkfXQbJNuMt5Jdi7dKFR6DR-Zf7B-A,8735
+pdftagger/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pdftagger/webhooks.py,sha256=oFMGOloMrf_uF9lIOqqvy5Ro3QRR5R5lUU6qko7ddcM,3575
+pdftagger-0.1.0.dist-info/METADATA,sha256=5AYnTCZ_JTigSpLEnbB9MCDNa1V1fhxW5-xwFdOd8uY,7904
+pdftagger-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pdftagger-0.1.0.dist-info/licenses/LICENSE,sha256=_n5jnbVB4wUObSq7ulIoCWxXqVkKNgZc_b0Mm9pMY7E,1067
+pdftagger-0.1.0.dist-info/RECORD,,

pdftagger-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

pdftagger-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PDF Tagger
+
+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.