pdfgate 0.0.2__py3-none-any.whl

pdfgate/pdfgate.py

@@ -0,0 +1,370 @@
+from typing import Any, Union, cast
+
+from pdfgate.http_client import PDFGateHTTPClientAsync, PDFGateHTTPClientSync
+from pdfgate.request_builder import RequestBuilder, get_domain_from_api_key
+from pdfgate.response_builder import ResponseBuilder
+
+from .errors import ParamsValidationError
+from .params import (
+    CompressPDFParams,
+    ExtractPDFFormDataParams,
+    FlattenPDFParams,
+    GeneratePDFParams,
+    GetDocumentParams,
+    GetFileParams,
+    ProtectPDFParams,
+    WatermarkPDFParams,
+)
+from .responses import PDFGateDocument
+
+
+class PDFGate:
+    """Client for the PDFGate API.
+
+    Attributes:
+        api_key (str):
+            API key used for authentication.
+        domain (str):
+            Base API domain derived from the API key.
+        request_builder (RequestBuilder):
+            Builds HTTP requests for the API from parameter objects.
+        sync_client (PDFGateHTTPClientSync):
+            Synchronous HTTP client that handles HTTP errors.
+        async_client (PDFGateHTTPClientAsync):
+            Asynchronous HTTP client that handles HTTP errors.
+    """
+
+    def __init__(self, api_key: str):
+        """Initialize a PDFGate client.
+
+        Args:
+            api_key: The API key to use. Must start with 'live_' or 'test_'.
+
+        Raises:
+            PDFGateError: If the API key is invalid.
+        """
+        self.domain = get_domain_from_api_key(api_key)
+        self.api_key = api_key
+        self.request_builder = RequestBuilder(api_key=api_key)
+        self.sync_client = PDFGateHTTPClientSync(api_key=api_key)
+        self.async_client = PDFGateHTTPClientAsync(api_key=api_key)
+
+    def get_document(self, params: GetDocumentParams) -> PDFGateDocument:
+        """Retrieve a stored document’s metadata (and optionally a fresh pre-signed download URL).
+
+        Returns:
+            A `PDFGateDocument` parsed from the JSON response.
+
+        Raises:
+            PDFGateError: If the HTTP request fails (including non-2xx responses) or if
+                there is a network/connection error. The error includes status code
+                and message when available.
+        """
+        request = self.request_builder.build_get_document(params)
+        response = self.sync_client.try_make_request(request)
+        result = cast(
+            PDFGateDocument, ResponseBuilder.build_response(response, json=True)
+        )
+
+        return result
+
+    async def get_document_async(self, params: GetDocumentParams) -> PDFGateDocument:
+        """Retrieve a stored document’s metadata (and optionally a fresh pre-signed download URL).
+
+        Returns:
+            A `PDFGateDocument` parsed from the JSON response.
+
+        Raises:
+            PDFGateError: If the HTTP request fails (including non-2xx responses) or if
+                there is a network/connection error. The error includes status code
+                and message when available.
+        """
+        request = self.request_builder.build_get_document(params)
+        response = await self.async_client.try_make_request_async(request)
+        result = cast(
+            PDFGateDocument, ResponseBuilder.build_response(response, json=True)
+        )
+
+        return result
+
+    def get_file(self, params: GetFileParams) -> bytes:
+        """Download a raw PDF file by its document ID.
+
+        Important: Accessing stored generated files requires enabling
+        “Save files” in the PDFGate Dashboard settings (disabled by default).
+
+        Returns:
+            The raw bytes of the file.
+        """
+        request = self.request_builder.build_get_file(params.document_id)
+        response = self.sync_client.try_make_request(request=request)
+
+        return response.content
+
+    async def get_file_async(self, params: GetFileParams) -> bytes:
+        """Download a raw PDF file by its document ID.
+
+        Important: Accessing stored generated files requires enabling
+        “Save files” in the PDFGate Dashboard settings (disabled by default).
+
+        Returns:
+            The raw bytes of the file.
+        """
+        request = self.request_builder.build_get_file(params.document_id)
+        response = await self.async_client.try_make_request_async(request=request)
+
+        return response.content
+
+    def generate_pdf(self, params: GeneratePDFParams) -> Union[bytes, PDFGateDocument]:
+        """Generate a PDF from a URL or raw HTML.
+
+        Returns:
+            Either the raw PDF bytes or a `PDFGateDocument` parsed from the JSON response.
+        """
+        if not params.html and not params.url:
+            raise ParamsValidationError(
+                "Either the 'html' or 'url' parameters must be provided to generate a PDF."
+            )
+
+        request = self.request_builder.build_generate_pdf(params)
+        response = self.sync_client.try_make_request(request)
+        result = ResponseBuilder.build_response(response, json=params.json_response)
+
+        return result
+
+    async def generate_pdf_async(
+        self, params: GeneratePDFParams
+    ) -> Union[bytes, PDFGateDocument]:
+        """Generate a PDF from a URL or raw HTML.
+
+        Returns:
+            Either the raw PDF bytes or a `PDFGateDocument` parsed from the JSON response.
+        """
+        if not params.html and not params.url:
+            raise ParamsValidationError(
+                "Either the 'html' or 'url' parameters must be provided to generate a PDF."
+            )
+
+        request = self.request_builder.build_generate_pdf(params)
+        response = await self.async_client.try_make_request_async(request)
+        result = ResponseBuilder.build_response(response, json=params.json_response)
+
+        return result
+
+    def flatten_pdf(self, params: FlattenPDFParams) -> Union[bytes, PDFGateDocument]:
+        """Flatten an interactive PDF into a static, non-editable PDF.
+
+        Args:
+            params: Either a `FlattenPDFByDocumentIdParams` or
+                `FlattenPDFBinaryParams` instance depending on whether the file
+                is provided as a document ID or raw binary data.
+
+        Returns:
+            Depending on the `json_response` flag in `params`, this method either
+            returns the raw PDF bytes or a `PDFGateDocument` instance.
+        """
+        request = self.request_builder.build_flatten_pdf(params)
+        response = self.sync_client.try_make_request(request)
+        result = ResponseBuilder.build_response(response, json=params.json_response)
+
+        return result
+
+    async def flatten_pdf_async(
+        self, params: FlattenPDFParams
+    ) -> Union[bytes, PDFGateDocument]:
+        """Flatten an interactive PDF into a static, non-editable PDF.
+
+        Args:
+            params: Either a `FlattenPDFByDocumentIdParams` or
+                `FlattenPDFBinaryParams` instance depending on whether the file
+                is provided as a document ID or raw binary data.
+
+        Returns:
+            Depending on the `json_response` flag in `params`, this method either
+            returns the raw PDF bytes or a `PDFGateDocument` instance.
+        """
+        request = self.request_builder.build_flatten_pdf(params)
+        response = await self.async_client.try_make_request_async(request)
+        result = ResponseBuilder.build_response(response, json=params.json_response)
+
+        return result
+
+    def extract_pdf_form_data(self, params: ExtractPDFFormDataParams) -> Any:
+        """Extract form field data from a fillable PDF and return it as JSON.
+
+        Args:
+            params: Either a `ExtractPDFFormDataByDocumentIdParams` or
+                `ExtractPDFFormDataBinaryParams` instance depending on whether the file
+                is provided as a document ID or raw binary data.
+
+        Returns:
+            JSON object mapping form field names to their values.
+        """
+        request = self.request_builder.build_extract_pdf_form_data(params)
+        response = self.sync_client.try_make_request(request)
+        result = ResponseBuilder.build_response(response, json=True)
+
+        return result
+
+    async def extract_pdf_form_data_async(
+        self, params: ExtractPDFFormDataParams
+    ) -> Any:
+        """Extract form field data from a fillable PDF and return it as JSON.
+
+        Args:
+            params: Either a `ExtractPDFFormDataByDocumentIdParams` or
+                `ExtractPDFFormDataBinaryParams` instance depending on whether the file
+                is provided as a document ID or raw binary data.
+
+        Returns:
+            JSON object mapping form field names to their values.
+        """
+        request = self.request_builder.build_extract_pdf_form_data(params)
+        response = await self.async_client.try_make_request_async(request)
+        result = ResponseBuilder.build_response(response, json=True)
+
+        return result
+
+    def protect_pdf(self, params: ProtectPDFParams) -> Union[bytes, PDFGateDocument]:
+        """Protect a PDF using encryption + optional permission restrictions.
+
+        Security options highlights:
+            - `algorithm`: `"AES256"` (default) or `"AES128"`.
+            - `user_password`: password required to open the PDF (optional).
+            - `owner_password`: full control password; required in some cases (e.g., AES256 with `user_password`).
+            - Restrictions: `disable_print`, `disable_copy`, `disable_editing`.
+            - `encrypt_metadata`: whether PDF metadata is encrypted (default `False`).
+
+        Args:
+            params: Either a `ProtectPDFByDocumentIdParams` or
+                `ProtectPDFBinaryParams` instance depending on whether the file
+                is provided as a document ID or raw binary data.
+
+        Returns:
+            Depending on the `json_response` flag in `params`, this method either
+            returns the raw PDF bytes or a `PDFGateDocument` instance.
+        """
+        request = self.request_builder.build_protect_pdf(params)
+        response = self.sync_client.try_make_request(request)
+        result = ResponseBuilder.build_response(response, json=params.json_response)
+
+        return result
+
+    async def protect_pdf_async(
+        self, params: ProtectPDFParams
+    ) -> Union[bytes, PDFGateDocument]:
+        """Protect a PDF using encryption + optional permission restrictions.
+
+        Security options highlights:
+            - `algorithm`: `"AES256"` (default) or `"AES128"`.
+            - `user_password`: password required to open the PDF (optional).
+            - `owner_password`: full control password; required in some cases (e.g., AES256 with `user_password`).
+            - Restrictions: `disable_print`, `disable_copy`, `disable_editing`.
+            - `encrypt_metadata`: whether PDF metadata is encrypted (default `False`).
+
+        Args:
+            params: Either a `ProtectPDFByDocumentIdParams` or
+                `ProtectPDFBinaryParams` instance depending on whether the file
+                is provided as a document ID or raw binary data.
+
+        Returns:
+            Depending on the `json_response` flag in `params`, this method either
+            returns the raw PDF bytes or a `PDFGateDocument` instance.
+        """
+        request = self.request_builder.build_protect_pdf(params)
+        response = await self.async_client.try_make_request_async(request)
+        result = ResponseBuilder.build_response(response, json=params.json_response)
+
+        return result
+
+    def compress_pdf(self, params: CompressPDFParams) -> Union[bytes, PDFGateDocument]:
+        """Compress a PDF document to reduce its size without changing its visual content.
+
+        Args:
+            params: Either a `CompressPDFByDocumentIdParams` or
+                `CompressPDFBinaryParams` instance depending on whether the file
+                is provided as a document ID or raw binary data.
+
+        Returns:
+            Depending on the `json_response` flag in `params`, this method either
+            returns the raw PDF bytes or a `PDFGateDocument` instance.
+        """
+        request = self.request_builder.build_compress_pdf(params)
+        response = self.sync_client.try_make_request(request)
+        result = ResponseBuilder.build_response(response, json=params.json_response)
+
+        return result
+
+    async def compress_pdf_async(
+        self, params: CompressPDFParams
+    ) -> Union[bytes, PDFGateDocument]:
+        """Compress a PDF document to reduce its size without changing its visual content.
+
+        Args:
+            params: Either a `CompressPDFByDocumentIdParams` or
+                `CompressPDFBinaryParams` instance depending on whether the file
+                is provided as a document ID or raw binary data.
+
+        Returns:
+            Depending on the `json_response` flag in `params`, this method either
+            returns the raw PDF bytes or a `PDFGateDocument` instance.
+        """
+        request = self.request_builder.build_compress_pdf(params)
+        response = await self.async_client.try_make_request_async(request)
+        result = ResponseBuilder.build_response(response, json=params.json_response)
+
+        return result
+
+    def watermark_pdf(self, params: WatermarkPDFParams) -> Any:
+        """Apply a text or image watermark to a PDF.
+
+        Watermark configuration highlights:
+            - `type` is required: `"text"` or `"image"`.
+            - For text watermarks: `text` required when `type="text"`.
+            - For image watermarks: upload `watermark` image file (`.png`, `.jpg`, `.jpeg`).
+            - Optional: `font` (standard PDF fonts), `fontFile`
+            (`.ttf`/`.otf` overrides `font`), `fontSize`, `fontColor`,
+            `opacity` (0..1), `xPosition`, `yPosition`, `imageWidth`, `imageHeight`,
+            `rotate` (0..360).
+
+        Args:
+            params: Either a `WatermarkPDFByDocumentIdParams` or
+                `WatermarkPDFByFileParams` instance depending on whether the file
+                is provided as a document ID or raw binary data.
+
+        Returns:
+            Depending on the `json_response` flag in `params`, this method either
+            returns the raw PDF bytes or a `PDFGateDocument` instance.
+        """
+        request = self.request_builder.build_watermark_pdf(params)
+        response = self.sync_client.try_make_request(request)
+        result = ResponseBuilder.build_response(response, json=params.json_response)
+
+        return result
+
+    async def watermark_pdf_async(self, params: WatermarkPDFParams) -> Any:
+        """Apply a text or image watermark to a PDF.
+
+        Watermark configuration highlights:
+            - `type` is required: `"text"` or `"image"`.
+            - For text watermarks: `text` required when `type="text"`.
+            - For image watermarks: upload `watermark` image file (`.png`, `.jpg`, `.jpeg`).
+            - Optional: `font` (standard PDF fonts), `fontFile`
+            (`.ttf`/`.otf` overrides `font`), `fontSize`, `fontColor`,
+            `opacity` (0..1), `xPosition`, `yPosition`, `imageWidth`, `imageHeight`,
+            `rotate` (0..360).
+
+        Args:
+            params: Either a `WatermarkPDFByDocumentIdParams` or
+                `WatermarkPDFByFileParams` instance depending on whether the file
+                is provided as a document ID or raw binary data.
+
+        Returns:
+            Depending on the `json_response` flag in `params`, this method either
+            returns the raw PDF bytes or a `PDFGateDocument` instance.
+        """
+        request = self.request_builder.build_watermark_pdf(params)
+        response = await self.async_client.try_make_request_async(request)
+        result = ResponseBuilder.build_response(response, json=params.json_response)
+
+        return result

pdfgate/request_builder.py

@@ -0,0 +1,252 @@
+"""Request construction utilities for PDFGate API calls."""
+
+from dataclasses import asdict, dataclass
+from datetime import timedelta
+from enum import Enum
+import mimetypes
+from typing import Any
+import httpx
+from pdfgate.config import Config
+from pdfgate.dict_keys_converter import snake_to_camel
+from pdfgate.errors import PDFGateError
+from pdfgate.params import (
+    CompressPDFByDocumentIdParams,
+    CompressPDFParams,
+    ExtractPDFFormDataByDocumentIdParams,
+    ExtractPDFFormDataParams,
+    FileParam,
+    FlattenPDFByFileParams,
+    FlattenPDFParams,
+    GeneratePDFParams,
+    GetDocumentParams,
+    PDFGateParams,
+    ProtectPDFByDocumentIdParams,
+    ProtectPDFParams,
+    WatermarkPDFByDocumentIdParams,
+    WatermarkPDFParams,
+    WatermarkType,
+)
+from pdfgate.url_builder import URLBuilder
+
+FormDataFileParam = tuple[str, bytes, str]
+
+
+def get_domain_from_api_key(api_key: str) -> str:
+    """Return the API domain corresponding to an API key.
+
+    Args:
+        api_key:
+            API key string that should start with 'live_' or 'test_'.
+
+    Returns:
+        The domain (URL) for the API (production or sandbox).
+
+    Raises:
+        PDFGateError: If the API key format is invalid.
+    """
+    if api_key.startswith("live_"):
+        return Config.PRODUCTION_API_DOMAIN
+    elif api_key.startswith("test_"):
+        return Config.SANDBOX_API_DOMAIN
+    else:
+        raise PDFGateError(
+            "Invalid API key format. Expected to start with 'live_' or 'test_'."
+        )
+
+
+def pdfgate_params_to_params_dict(instance: PDFGateParams) -> dict[str, Any]:
+    """Convert a params dataclass into a JSON-ready dict."""
+    params_dict = asdict(instance)
+    params_without_nulls: dict[str, Any] = {}
+    for k, v in params_dict.items():
+        if v is not None:
+            params_without_nulls[snake_to_camel(k)] = (
+                v.value if isinstance(v, Enum) else v
+            )
+
+    return params_without_nulls
+
+
+@dataclass
+class PDFGateRequest:
+    """Container for an HTTP request and its timeout."""
+
+    request: httpx.Request
+    timeout: int = int(
+        timedelta(seconds=Config.DEFAULT_TIMEOUT_SECONDS).total_seconds()
+    )
+
+
+class RequestBuilder:
+    """Build HTTP requests for PDFGate endpoints."""
+
+    def __init__(self, api_key: str):
+        domain = get_domain_from_api_key(api_key)
+        self.url_builder = URLBuilder(domain)
+        self.api_key = api_key
+
+    def get_headers(self) -> dict[str, str]:
+        """Return the authorization header for API calls."""
+        return {"Authorization": f"Bearer {self.api_key}"}
+
+    def _get_request(self, url: str, params: dict[str, Any] = {}) -> httpx.Request:
+        """Create a GET request with standard headers."""
+        return httpx.Request("GET", url=url, headers=self.get_headers(), params=params)
+
+    def _json_post_request(self, url: str, json: dict[str, Any]) -> httpx.Request:
+        """Create a JSON POST request with standard headers."""
+        return httpx.Request("POST", url=url, headers=self.get_headers(), json=json)
+
+    def _multipart_post_request(
+        self, url: str, data: dict[str, Any] = {}, files: dict[str, Any] = {}
+    ) -> httpx.Request:
+        """Create a multipart POST request with standard headers."""
+        return httpx.Request(
+            "POST", url=url, headers=self.get_headers(), data=data, files=files
+        )
+
+    def _build_file_param(
+        self, file_param: FileParam, key: str
+    ) -> dict[str, FormDataFileParam]:
+        """Build a file parameter for multipart requests."""
+        if file_param.type is None:
+            mime_type, _encoding = mimetypes.guess_type(file_param.name)
+            mime_type = mime_type or "application/octet-stream"
+        else:
+            mime_type = file_param.type or "application/octet-stream"
+
+        return {key: (file_param.name, file_param.data, mime_type)}
+
+    def build_get_file(self, document_id: str) -> PDFGateRequest:
+        """Build a request to download a document's file content."""
+        url = self.url_builder.get_file_url(document_id)
+        request = self._get_request(url)
+
+        return PDFGateRequest(request=request)
+
+    def build_get_document(self, params: GetDocumentParams) -> PDFGateRequest:
+        """Build a request to fetch a document's metadata."""
+        params_dict: dict[str, int] = {}
+        if params.pre_signed_url_expires_in is not None:
+            params_dict["preSignedUrlExpiresIn"] = params.pre_signed_url_expires_in
+
+        url = self.url_builder.get_document_url(params.document_id)
+        request = self._get_request(url, params_dict)
+
+        return PDFGateRequest(request=request)
+
+    def build_generate_pdf(self, params: GeneratePDFParams) -> PDFGateRequest:
+        """Build a request to generate a PDF from HTML or URL."""
+        url = self.url_builder.generate_pdf_url()
+        params_without_nulls = pdfgate_params_to_params_dict(params)
+        request = self._json_post_request(url, json=params_without_nulls)
+        timeout = int(
+            timedelta(minutes=Config.GENERATE_PDF_TIMEOUT_MINUTES).total_seconds()
+        )
+
+        return PDFGateRequest(request=request, timeout=timeout)
+
+    def build_flatten_pdf(self, params: FlattenPDFParams) -> PDFGateRequest:
+        """Build a request to flatten a PDF from file or document ID."""
+        url = self.url_builder.flatten_pdf_url()
+        params_without_nulls = pdfgate_params_to_params_dict(params)
+        if isinstance(params, FlattenPDFByFileParams) and params.file is not None:
+            files = self._build_file_param(params_without_nulls.pop("file"), "file")
+        else:
+            files = {}
+
+        request = self._multipart_post_request(
+            url, data=params_without_nulls, files=files
+        )
+        timeout = int(
+            timedelta(minutes=Config.FLATTEN_PDF_TIMEOUT_MINUTES).total_seconds()
+        )
+
+        return PDFGateRequest(request=request, timeout=timeout)
+
+    def build_extract_pdf_form_data(
+        self, params: ExtractPDFFormDataParams
+    ) -> PDFGateRequest:
+        """Build a request to extract PDF form data."""
+        url = self.url_builder.extract_pdf_form_data_url()
+        if isinstance(params, ExtractPDFFormDataByDocumentIdParams):
+            params_dict = {"documentId": params.document_id}
+            request = self._multipart_post_request(url, data=params_dict)
+        else:
+            files = self._build_file_param(params.file, "file")
+            request = self._multipart_post_request(url, files=files)
+
+        return PDFGateRequest(request=request)
+
+    def build_protect_pdf(self, params: ProtectPDFParams) -> PDFGateRequest:
+        """Build a request to encrypt a PDF from file or document ID."""
+        url = self.url_builder.protect_pdf_url()
+        params_without_nulls = pdfgate_params_to_params_dict(params)
+        if isinstance(params, ProtectPDFByDocumentIdParams):
+            request = self._multipart_post_request(url=url, data=params_without_nulls)
+        else:
+            file_param = {"file": params_without_nulls.pop("file", None)}
+            request = self._multipart_post_request(
+                url=url,
+                data=params_without_nulls,
+                files=file_param,
+            )
+        timeout = int(
+            timedelta(minutes=Config.PROTECT_PDF_TIMEOUT_MINUTES).total_seconds()
+        )
+
+        return PDFGateRequest(request=request, timeout=timeout)
+
+    def build_compress_pdf(self, params: CompressPDFParams) -> PDFGateRequest:
+        """Build a request to compress a PDF from file or document ID."""
+        url = self.url_builder.compress_pdf_url()
+        params_without_nulls = pdfgate_params_to_params_dict(params)
+        if isinstance(params, CompressPDFByDocumentIdParams):
+            request = self._multipart_post_request(url=url, data=params_without_nulls)
+        else:
+            file_param = {"file": params_without_nulls.pop("file", None)}
+            request = self._multipart_post_request(
+                url=url,
+                data=params_without_nulls,
+                files=file_param,
+            )
+        timeout = int(
+            timedelta(minutes=Config.COMPRESS_PDF_TIMEOUT_MINUTES).total_seconds()
+        )
+
+        return PDFGateRequest(request=request, timeout=timeout)
+
+    def build_watermark_pdf(self, params: WatermarkPDFParams) -> PDFGateRequest:
+        """Build a request to watermark a PDF from file or document ID."""
+        url = self.url_builder.watermark_pdf_url()
+        params_dict = pdfgate_params_to_params_dict(params)
+        if isinstance(params, WatermarkPDFByDocumentIdParams):
+            if params.type == WatermarkType.TEXT:
+                request = self._multipart_post_request(url=url, data=params_dict)
+            else:
+                watermark_file_param = self._build_file_param(
+                    params_dict.pop("watermark"), "watermark"
+                )
+                request = self._multipart_post_request(
+                    url=url,
+                    data=params_dict,
+                    files=watermark_file_param,
+                )
+        else:
+            if params.type == WatermarkType.IMAGE:
+                watermark_file_param = self._build_file_param(
+                    params_dict.pop("watermark"), "watermark"
+                )
+            else:
+                watermark_file_param = {}
+            file_param = self._build_file_param(params_dict.pop("file"), "file")
+            request = self._multipart_post_request(
+                url=url,
+                data=params_dict,
+                files={**file_param, **watermark_file_param},
+            )
+        timeout = int(
+            timedelta(minutes=Config.WATERMARK_PDF_TIMEOUT_MINUTES).total_seconds()
+        )
+
+        return PDFGateRequest(request=request, timeout=timeout)

pdfgate/response_builder.py

@@ -0,0 +1,23 @@
+"""Helpers for converting HTTP responses into SDK return types."""
+
+from typing import Optional, Union, cast
+
+import httpx
+
+from pdfgate.dict_keys_converter import convert_camel_keys_to_snake
+from pdfgate.responses import PDFGateDocument
+
+
+class ResponseBuilder:
+    """Build SDK responses from HTTP responses."""
+
+    @staticmethod
+    def build_response(
+        response: httpx.Response, json: Optional[bool] = False
+    ) -> Union[bytes, PDFGateDocument]:
+        """Convert an HTTP response into raw bytes or a document object."""
+        if json:
+            json_response = response.json()
+            return cast(PDFGateDocument, convert_camel_keys_to_snake(json_response))
+
+        return response.content

pdfgate/responses.py

@@ -0,0 +1,37 @@
+"""Response models for PDFGate API results."""
+
+from datetime import datetime
+from enum import Enum
+from typing import Any, Optional, TypedDict
+
+
+class DocumentStatus(Enum):
+    COMPLETED = "completed"
+    PROCESSING = "processing"
+    EXPIRED = "expired"
+    FAILED = "failed"
+
+
+class DocumentType(Enum):
+    """Document types reported by the PDFGate API."""
+
+    FROM_HTML = "from_html"
+    FLATTENED = "flattened"
+    WATERMARKED = "watermarked"
+    ENCRYPTED = "encrypted"
+    COMPRESSED = "compressed"
+    SIGNED = "signed"
+
+
+class PDFGateDocument(TypedDict, total=False):
+    """Typed dictionary representing a PDFGate document response."""
+
+    id: str
+    status: DocumentStatus
+    created_at: datetime
+    expires_at: datetime
+    type: Optional[DocumentType]
+    file_url: Optional[str]
+    size: Optional[int]
+    metadata: Optional[dict[str, Any]]
+    derived_from: Optional[str]