exportflow 1.0.0__py3-none-any.whl

exportflow/__init__.py

@@ -0,0 +1,91 @@
+"""The official Python SDK for the ExportFlow API.
+
+    from exportflow import ExportFlow
+
+    client = ExportFlow(api_key="exfk_test_...")
+    document = client.documents.upload(file="invoice.pdf")
+    document = client.documents.wait(document.id)
+    print(client.documents.extraction(document.id).as_dict())
+
+Documentation: https://exportflow.app/developers
+"""
+
+from . import webhooks
+from ._client import DEFAULT_BASE_URL, ExportFlow
+from ._errors import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    ConflictError,
+    ExportFlowError,
+    IncompatibleAPIVersionError,
+    InvalidRequestError,
+    NotFoundError,
+    PermissionDeniedError,
+    ProcessingFailedError,
+    QuotaExceededError,
+    RateLimitError,
+    SDKVersionUnsupportedError,
+    ServerError,
+    SignatureVerificationError,
+    WaitTimeoutError,
+)
+from ._models import (
+    Document,
+    ExtractedField,
+    Extraction,
+    Finding,
+    Identity,
+    MeterUsage,
+    ProcessingAccepted,
+    Reading,
+    Record,
+    RecordField,
+    Shipment,
+    Usage,
+    Verification,
+    WebhookEndpoint,
+    WebhookEvent,
+)
+from ._version import API_MAJOR_VERSION, __version__
+
+__all__ = [
+    "API_MAJOR_VERSION",
+    "DEFAULT_BASE_URL",
+    "APIConnectionError",
+    "APIError",
+    "APITimeoutError",
+    "AuthenticationError",
+    "ConflictError",
+    "Document",
+    "ExportFlow",
+    "ExportFlowError",
+    "ExtractedField",
+    "Extraction",
+    "Finding",
+    "Identity",
+    "IncompatibleAPIVersionError",
+    "InvalidRequestError",
+    "MeterUsage",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "ProcessingAccepted",
+    "ProcessingFailedError",
+    "QuotaExceededError",
+    "RateLimitError",
+    "Reading",
+    "Record",
+    "RecordField",
+    "SDKVersionUnsupportedError",
+    "ServerError",
+    "Shipment",
+    "SignatureVerificationError",
+    "Usage",
+    "Verification",
+    "WaitTimeoutError",
+    "WebhookEndpoint",
+    "WebhookEvent",
+    "__version__",
+    "webhooks",
+]

exportflow/_client.py

@@ -0,0 +1,614 @@
+"""The client.
+
+    from exportflow import ExportFlow
+
+    client = ExportFlow(api_key="exfk_test_...")
+
+    document = client.documents.upload(file="invoice.pdf", document_type="commercial_invoice")
+    document = client.documents.wait(document.id)
+    fields = client.documents.extraction(document.id).as_dict()
+
+Three things the client does so your code does not have to:
+
+**Retries that cannot double-charge.** Every request that changes something
+carries an ``Idempotency-Key``. When a request times out or the API answers
+429 or 5xx, the client waits and sends the *same* request with the *same* key,
+so the work is done once however many times it is sent.
+
+**Errors you can branch on.** Every failure is an
+:class:`~exportflow.ExportFlowError`; one the API returned carries its
+documented ``code``.
+
+**A version check.** The API states its version on every response. If it is a
+different major version from the one this SDK was built for, the client
+raises rather than misread the response.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import mimetypes
+import os
+import platform
+import random
+import time
+import uuid
+from typing import IO, Any, Dict, Iterable, List, Mapping, Optional, Tuple, Union
+
+import httpx
+
+from ._errors import (
+    APIConnectionError,
+    APIError,
+    APITimeoutError,
+    AuthenticationError,
+    ConflictError,
+    IncompatibleAPIVersionError,
+    InvalidRequestError,
+    NotFoundError,
+    PermissionDeniedError,
+    ProcessingFailedError,
+    QuotaExceededError,
+    RateLimitError,
+    SDKVersionUnsupportedError,
+    ServerError,
+    WaitTimeoutError,
+)
+from ._models import (
+    Document,
+    Extraction,
+    Identity,
+    ProcessingAccepted,
+    Record,
+    Shipment,
+    Usage,
+    Verification,
+    WebhookEndpoint,
+)
+from ._version import API_MAJOR_VERSION, __version__
+
+__all__ = ["DEFAULT_BASE_URL", "ExportFlow"]
+
+DEFAULT_BASE_URL = "https://api.exportflow.app"
+API_PREFIX = "/public/v1"
+VERSION_HEADER = "ExportFlow-Api-Version"
+IDEMPOTENCY_HEADER = "Idempotency-Key"
+
+FileInput = Union[str, "os.PathLike[str]", bytes, IO[bytes]]
+
+_QUOTA_CODES = frozenset({"quota_exceeded", "spend_limit_reached"})
+_NOT_RETRYABLE_429 = _QUOTA_CODES
+
+
+def _user_agent() -> str:
+    return (
+        f"exportflow-python/{__version__} "
+        f"python/{platform.python_version()} httpx/{httpx.__version__}"
+    )
+
+
+def _read_file(file: FileInput, filename: Optional[str]) -> Tuple[bytes, str]:
+    if isinstance(file, (bytes, bytearray)):
+        return bytes(file), filename or "document"
+    if isinstance(file, (str, os.PathLike)):
+        path = os.fspath(file)
+        with open(path, "rb") as handle:
+            return handle.read(), filename or os.path.basename(path)
+    content = file.read()
+    name = filename or os.path.basename(str(getattr(file, "name", "") or "document"))
+    return content, name
+
+
+_SIGNATURES: Tuple[Tuple[bytes, str], ...] = (
+    (b"%PDF", "application/pdf"),
+    (b"\x89PNG\r\n\x1a\n", "image/png"),
+    (b"\xff\xd8\xff", "image/jpeg"),
+    (b"II*\x00", "image/tiff"),
+    (b"MM\x00*", "image/tiff"),
+)
+
+
+def _media_type(content: bytes, filename: str) -> str:
+    """What the file is, from its first bytes; its name is only a fallback.
+
+    The API checks the declared type against the content and refuses a
+    mismatch, so a PDF passed as bytes with no name must still be declared a
+    PDF. The content is the evidence; a file's name is whatever somebody
+    typed.
+    """
+    for signature, media_type in _SIGNATURES:
+        if content.startswith(signature):
+            return media_type
+    if content[:4] == b"RIFF" and content[8:12] == b"WEBP":
+        return "image/webp"
+    return mimetypes.guess_type(filename)[0] or "application/octet-stream"
+
+
+def _multipart(content: bytes, filename: str, media_type: str) -> Tuple[bytes, str]:
+    """One file as multipart/form-data, built once so a retry sends the same bytes."""
+    boundary = f"exportflow-{uuid.uuid4().hex}"
+    safe_name = filename.replace("\\", "_").replace('"', "_").replace("\r", "").replace("\n", "")
+    head = (
+        f"--{boundary}\r\n"
+        f'Content-Disposition: form-data; name="file"; filename="{safe_name}"\r\n'
+        f"Content-Type: {media_type}\r\n\r\n"
+    ).encode()
+    return head + content + f"\r\n--{boundary}--\r\n".encode(), boundary
+
+
+class ExportFlow:
+    """A client for the ExportFlow API.
+
+    :param api_key: Your API key. Defaults to the ``EXPORTFLOW_API_KEY``
+        environment variable. A key beginning ``exfk_test_`` uses the sandbox;
+        ``exfk_live_`` uses production.
+    :param base_url: The API's address. Change it only for a private deployment.
+    :param timeout: Seconds to wait for one response.
+    :param max_retries: How many times to send a request again after a
+        connection failure, a 429 or a 5xx. ``0`` disables retries.
+    :param http_client: An ``httpx.Client`` to use, for a proxy, custom TLS or tests.
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 60.0,
+        max_retries: int = 2,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        key = api_key or os.environ.get("EXPORTFLOW_API_KEY")
+        if not key:
+            raise ValueError(
+                "An API key is required: pass api_key=... or set EXPORTFLOW_API_KEY. "
+                "Create one in the developer console."
+            )
+        self._api_key = key
+        self._base_url = (
+            base_url or os.environ.get("EXPORTFLOW_BASE_URL") or DEFAULT_BASE_URL
+        ).rstrip("/")
+        self._max_retries = max(int(max_retries), 0)
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self._sleep = time.sleep
+
+        self.shipments = Shipments(self)
+        self.documents = Documents(self)
+        self.records = Records(self)
+        self.verifications = Verifications(self)
+        self.usage = UsageResource(self)
+        self.webhook_endpoints = WebhookEndpoints(self)
+
+    # -- lifecycle ---------------------------------------------------------------------
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._http.close()
+
+    def __enter__(self) -> "ExportFlow":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        # Never the key: a client that prints its key puts it in a log.
+        return f"ExportFlow(environment={self.environment!r}, base_url={self._base_url!r})"
+
+    @property
+    def environment(self) -> str:
+        """``sandbox`` or ``production``, read from the key's prefix."""
+        return "sandbox" if self._api_key.startswith("exfk_test_") else "production"
+
+    def me(self) -> Identity:
+        """Who this key is. A good first call: it proves the key works."""
+        return Identity._build(self._request("GET", "/me"))
+
+    # -- transport ---------------------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json: Optional[Any] = None,
+        content: Optional[bytes] = None,
+        content_type: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        headers: Dict[str, str] = {
+            "Authorization": f"Bearer {self._api_key}",
+            "User-Agent": _user_agent(),
+            "Accept": "application/json",
+        }
+        if method != "GET":
+            headers[IDEMPOTENCY_HEADER] = idempotency_key or uuid.uuid4().hex
+        if content_type:
+            headers["Content-Type"] = content_type
+        url = f"{self._base_url}{API_PREFIX}{path}"
+        query = {k: v for k, v in (params or {}).items() if v is not None}
+
+        attempt = 0
+        while True:
+            try:
+                response = self._http.request(
+                    method, url, params=query or None, json=json, content=content, headers=headers
+                )
+            except httpx.TimeoutException as error:
+                if attempt >= self._max_retries:
+                    raise APITimeoutError("The ExportFlow API did not answer in time.") from error
+                self._wait(attempt, None)
+                attempt += 1
+                continue
+            except httpx.HTTPError as error:
+                if attempt >= self._max_retries:
+                    raise APIConnectionError(
+                        f"The ExportFlow API could not be reached ({type(error).__name__})."
+                    ) from error
+                self._wait(attempt, None)
+                attempt += 1
+                continue
+
+            if response.status_code < 400:
+                self._check_version(response)
+                if response.status_code == 204 or not response.content:
+                    return None
+                return response.json()
+
+            error = self._error(response)
+            retryable = isinstance(error, ServerError) or (
+                isinstance(error, (RateLimitError, ConflictError))
+                and error.code in ("rate_limited", "request_in_progress", "idempotency_conflict")
+            )
+            if not retryable or attempt >= self._max_retries:
+                raise error
+            self._wait(attempt, getattr(error, "retry_after", None))
+            attempt += 1
+
+    def _wait(self, attempt: int, retry_after: Optional[float]) -> None:
+        if retry_after is not None:
+            delay = min(max(retry_after, 0.0), 60.0)
+        else:
+            delay = min(0.5 * (2**attempt), 8.0)
+        # Jitter, so many clients that failed together do not retry together.
+        self._sleep(delay + random.uniform(0, delay / 4))  # noqa: S311 - not security
+
+    @staticmethod
+    def _check_version(response: httpx.Response) -> None:
+        stated = response.headers.get(VERSION_HEADER)
+        if not stated:
+            return
+        try:
+            major = int(stated.split(".")[0])
+        except ValueError:
+            return
+        if major != API_MAJOR_VERSION:
+            raise IncompatibleAPIVersionError(
+                f"The API is version {stated}; this SDK ({__version__}) speaks version "
+                f"{API_MAJOR_VERSION}. Install the SDK release for that API version."
+            )
+
+    @staticmethod
+    def _error(response: httpx.Response) -> APIError:
+        code, message = "error", f"The API answered {response.status_code}."
+        try:
+            body = response.json()
+            if isinstance(body, dict) and isinstance(body.get("error"), dict):
+                code = str(body["error"].get("code") or code)
+                message = str(body["error"].get("message") or message)
+            elif isinstance(body, dict) and "detail" in body:
+                # A request the API could not parse at all.
+                code, message = "invalid_request", _validation_message(body["detail"])
+        except ValueError:
+            pass
+        request_id = response.headers.get("x-request-id")
+        status = response.status_code
+        common: Dict[str, Any] = {"status_code": status, "code": code, "request_id": request_id}
+        if status == 401:
+            return AuthenticationError(message, **common)
+        if status == 403:
+            return PermissionDeniedError(message, **common)
+        if status == 404:
+            return NotFoundError(message, **common)
+        if status == 409:
+            return ConflictError(message, **common)
+        if status == 426:
+            return SDKVersionUnsupportedError(message, **common)
+        if status == 429:
+            header = response.headers.get("Retry-After")
+            retry_after = float(header) if header and header.replace(".", "", 1).isdigit() else None
+            kind = QuotaExceededError if code in _QUOTA_CODES else RateLimitError
+            return kind(message, retry_after=retry_after, **common)
+        if status >= 500:
+            return ServerError(message, **common)
+        return InvalidRequestError(message, **common)
+
+
+def _validation_message(detail: Any) -> str:
+    if isinstance(detail, list) and detail:
+        first = detail[0]
+        if isinstance(first, dict):
+            where = ".".join(str(part) for part in first.get("loc", []) if part != "body")
+            return f"{where}: {first.get('msg', 'invalid')}" if where else str(first.get("msg"))
+    return str(detail)
+
+
+class _Resource:
+    def __init__(self, client: ExportFlow) -> None:
+        self._client = client
+
+
+class Shipments(_Resource):
+    """A shipment is a set of documents that are checked against each other."""
+
+    def create(
+        self,
+        *,
+        reference: Optional[str] = None,
+        commodity: Optional[str] = None,
+        exporter_name: Optional[str] = None,
+        origin_country: Optional[str] = None,
+        destination_country: Optional[str] = None,
+        destination_port: Optional[str] = None,
+        hs_code: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Shipment:
+        body = {
+            "reference": reference,
+            "commodity": commodity,
+            "exporter_name": exporter_name,
+            "origin_country": origin_country,
+            "destination_country": destination_country,
+            "destination_port": destination_port,
+            "hs_code": hs_code,
+        }
+        return Shipment._build(
+            self._client._request(
+                "POST",
+                "/shipments",
+                json={k: v for k, v in body.items() if v is not None},
+                idempotency_key=idempotency_key,
+            )
+        )
+
+    def get(self, shipment_id: str) -> Shipment:
+        return Shipment._build(self._client._request("GET", f"/shipments/{shipment_id}"))
+
+    def list(self, *, reference: Optional[str] = None, limit: int = 50) -> List[Shipment]:
+        """The most recent shipments, newest first."""
+        found = self._client._request(
+            "GET", "/shipments", params={"reference": reference, "limit": limit}
+        )
+        return [Shipment._build(item) for item in found["data"]]
+
+
+class Documents(_Resource):
+    def upload(
+        self,
+        file: FileInput,
+        *,
+        shipment_id: Optional[str] = None,
+        document_type: Optional[str] = None,
+        filename: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Document:
+        """Upload one document; it is scanned, stored and queued for processing.
+
+        :param file: A path, bytes, or a file opened in binary mode.
+        :param shipment_id: The shipment the document belongs to. If omitted, a
+            new shipment is created for it; read it from ``document.shipment_id``.
+        :param document_type: What you say the document is, for example
+            ``commercial_invoice`` or ``bill_of_lading``. Optional: the type is
+            detected, and your declaration is kept beside the detected one.
+
+        Processing is asynchronous. Call :meth:`wait`, or subscribe to the
+        ``document.processing.completed`` webhook.
+        """
+        content, name = _read_file(file, filename)
+        key = idempotency_key or uuid.uuid4().hex
+        if shipment_id is None:
+            # Derived from the upload's key, so a retried upload finds the
+            # shipment the first attempt made instead of making another.
+            shipment_id = self._client.shipments.create(idempotency_key=f"{key}-shipment").id
+        media_type = _media_type(content, name)
+        body, boundary = _multipart(content, name, media_type)
+        return Document._build(
+            self._client._request(
+                "POST",
+                f"/shipments/{shipment_id}/documents",
+                params={"document_type": document_type},
+                content=body,
+                content_type=f"multipart/form-data; boundary={boundary}",
+                idempotency_key=key,
+            )
+        )
+
+    def get(self, document_id: str) -> Document:
+        """The document and its processing status."""
+        return Document._build(self._client._request("GET", f"/documents/{document_id}"))
+
+    def list(self, shipment_id: str) -> List[Document]:
+        found = self._client._request("GET", f"/shipments/{shipment_id}/documents")
+        return [Document._build(item) for item in found["data"]]
+
+    def process(
+        self, document_id: str, *, idempotency_key: Optional[str] = None
+    ) -> ProcessingAccepted:
+        """Process a document again after it failed.
+
+        A document is processed automatically when it is uploaded, so you do
+        not need to call this in the ordinary case. It is safe to call at any
+        time: for a document that is being processed or has been processed it
+        changes nothing and returns ``queued=False``.
+        """
+        return ProcessingAccepted._build(
+            self._client._request(
+                "POST", f"/documents/{document_id}/process", idempotency_key=idempotency_key
+            )
+        )
+
+    def extraction(self, document_id: str) -> Extraction:
+        """The fields read from the document. Empty until it is ``processed``."""
+        return Extraction._build(
+            self._client._request("GET", f"/documents/{document_id}/extraction")
+        )
+
+    def wait(
+        self,
+        document_id: str,
+        *,
+        timeout: float = 300.0,
+        poll_interval: float = 2.0,
+        raise_on_failure: bool = True,
+    ) -> Document:
+        """Poll until the document's processing has finished.
+
+        Raises :class:`~exportflow.WaitTimeoutError` after ``timeout`` seconds
+        (the work continues) and, unless ``raise_on_failure`` is false,
+        :class:`~exportflow.ProcessingFailedError` if processing failed.
+        """
+        deadline = time.monotonic() + timeout
+        while True:
+            document = self.get(document_id)
+            if document.is_finished:
+                if document.status == "failed" and raise_on_failure:
+                    raise ProcessingFailedError(
+                        document.error or "The document could not be processed.",
+                        resource_id=document.id,
+                    )
+                return document
+            if time.monotonic() >= deadline:
+                raise WaitTimeoutError(
+                    f"Document {document_id} was still '{document.status}' after {timeout:g}s."
+                )
+            self._client._sleep(poll_interval)
+
+
+class Records(_Resource):
+    """What a shipment's documents say, and what has been confirmed."""
+
+    def get(self, shipment_id: str) -> Record:
+        return Record._build(self._client._request("GET", f"/shipments/{shipment_id}/record"))
+
+    def confirm(
+        self,
+        shipment_id: str,
+        fields: Union[Mapping[str, Optional[str]], Iterable[Mapping[str, Any]]],
+        *,
+        idempotency_key: Optional[str] = None,
+    ) -> Record:
+        """Confirm the values a person has checked against the documents.
+
+        ``fields`` is either ``{"port_of_discharge": "NHAVA SHEVA"}`` or a list
+        of ``{"name", "value" | "absence_reason", "source_extraction_id"}``.
+        Verification will not start until the record is confirmed: confirm
+        what the documents say, not what they should say.
+        """
+        if isinstance(fields, Mapping):
+            items: List[Dict[str, Any]] = [
+                {"name": name, "value": value} for name, value in fields.items()
+            ]
+        else:
+            items = [dict(item) for item in fields]
+        return Record._build(
+            self._client._request(
+                "PUT",
+                f"/shipments/{shipment_id}/record",
+                json={"fields": items},
+                idempotency_key=idempotency_key,
+            )
+        )
+
+
+class Verifications(_Resource):
+    def create(self, shipment_id: str, *, idempotency_key: Optional[str] = None) -> Verification:
+        """Check a shipment's confirmed record against the published rule set.
+
+        Asynchronous: call :meth:`wait` or subscribe to
+        ``verification.completed``. Raises :class:`~exportflow.ConflictError`
+        with code ``not_confirmed`` until the record has been confirmed.
+        """
+        return Verification._build(
+            self._client._request(
+                "POST", f"/shipments/{shipment_id}/verifications", idempotency_key=idempotency_key
+            )
+        )
+
+    def get(self, verification_id: str) -> Verification:
+        return Verification._build(
+            self._client._request("GET", f"/verifications/{verification_id}")
+        )
+
+    def list(self, shipment_id: str) -> List[Verification]:
+        found = self._client._request("GET", f"/shipments/{shipment_id}/verifications")
+        return [Verification._build(item) for item in found["data"]]
+
+    def wait(
+        self,
+        verification_id: str,
+        *,
+        timeout: float = 300.0,
+        poll_interval: float = 2.0,
+        raise_on_failure: bool = True,
+    ) -> Verification:
+        deadline = time.monotonic() + timeout
+        while True:
+            verification = self.get(verification_id)
+            if verification.is_finished:
+                if verification.status == "failed" and raise_on_failure:
+                    raise ProcessingFailedError(
+                        verification.failure_reason or "The verification failed.",
+                        resource_id=verification.id,
+                    )
+                return verification
+            if time.monotonic() >= deadline:
+                raise WaitTimeoutError(
+                    f"Verification {verification_id} was still '{verification.status}' "
+                    f"after {timeout:g}s."
+                )
+            self._client._sleep(poll_interval)
+
+
+class UsageResource(_Resource):
+    def get(self, period: Optional[Union[str, dt.date]] = None) -> Usage:
+        """This application's usage for a month (``"2026-11"``); the current
+        month if omitted. Charges are estimates until an invoice is issued."""
+        if isinstance(period, dt.date):
+            period = period.strftime("%Y-%m")
+        return Usage._build(self._client._request("GET", "/usage", params={"period": period}))
+
+
+class WebhookEndpoints(_Resource):
+    def create(
+        self,
+        url: str,
+        *,
+        event_types: Optional[Iterable[str]] = None,
+        description: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> WebhookEndpoint:
+        """Register an endpoint. The returned ``signing_secret`` is what you
+        verify deliveries with; store it."""
+        return WebhookEndpoint._build(
+            self._client._request(
+                "POST",
+                "/webhook_endpoints",
+                json={
+                    "url": url,
+                    "event_types": list(event_types or []),
+                    "description": description,
+                },
+                idempotency_key=idempotency_key,
+            )
+        )
+
+    def list(self) -> List[WebhookEndpoint]:
+        found = self._client._request("GET", "/webhook_endpoints")
+        return [WebhookEndpoint._build(item) for item in found["data"]]
+
+    def delete(self, endpoint_id: str, *, idempotency_key: Optional[str] = None) -> None:
+        self._client._request(
+            "DELETE", f"/webhook_endpoints/{endpoint_id}", idempotency_key=idempotency_key
+        )