exportflow 1.0.0__py3-none-any.whl

exportflow/_errors.py

@@ -0,0 +1,140 @@
+"""Errors.
+
+Every failure the SDK can report is an :class:`ExportFlowError`. An error the
+API answered with carries the API's own ``code`` -- stable, documented, and
+the thing to branch on -- plus the HTTP status and the request id to quote to
+support. The message is for people and may be reworded.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+__all__ = [
+    "APIConnectionError",
+    "APIError",
+    "APITimeoutError",
+    "AuthenticationError",
+    "ConflictError",
+    "ExportFlowError",
+    "IncompatibleAPIVersionError",
+    "InvalidRequestError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "ProcessingFailedError",
+    "QuotaExceededError",
+    "RateLimitError",
+    "SDKVersionUnsupportedError",
+    "ServerError",
+    "SignatureVerificationError",
+    "WaitTimeoutError",
+]
+
+
+class ExportFlowError(Exception):
+    """The base of every error this SDK raises."""
+
+
+class APIConnectionError(ExportFlowError):
+    """The API could not be reached. The request may or may not have arrived;
+    repeating it with the same idempotency key is safe."""
+
+
+class APITimeoutError(APIConnectionError):
+    """The API did not answer in time."""
+
+
+class APIError(ExportFlowError):
+    """The API answered with an error."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        code: str,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        """Machine-readable and stable, for example ``quota_exceeded``."""
+        self.request_id = request_id
+        """Quote this to ExportFlow support."""
+
+    def __str__(self) -> str:
+        suffix = f" (request {self.request_id})" if self.request_id else ""
+        return f"{self.code}: {self.message}{suffix}"
+
+
+class AuthenticationError(APIError):
+    """401. The API key is missing, wrong, revoked or expired."""
+
+
+class PermissionDeniedError(APIError):
+    """403. The key is valid and may not do this: a missing scope, a suspended
+    account, a disabled application or a network that is not allowed."""
+
+
+class NotFoundError(APIError):
+    """404. No such resource in this key's organisation and environment."""
+
+
+class ConflictError(APIError):
+    """409. The request cannot be done in the resource's current state, for
+    example verifying a shipment whose record has not been confirmed."""
+
+
+class InvalidRequestError(APIError):
+    """400 or 422. The request itself is wrong; repeating it will not help."""
+
+
+class RateLimitError(APIError):
+    """429. Too many requests. ``retry_after`` says how long to wait."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        code: str,
+        request_id: Optional[str] = None,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, code=code, request_id=request_id)
+        self.retry_after = retry_after
+
+
+class QuotaExceededError(RateLimitError):
+    """429. The account's allowance or spending limit for the period is used
+    up. Waiting a few seconds will not help; it resets with the period."""
+
+
+class ServerError(APIError):
+    """5xx. Something failed on ExportFlow's side. Safe to retry."""
+
+
+class SDKVersionUnsupportedError(APIError):
+    """426. This version of the SDK is too old for the API. Upgrade it."""
+
+
+class IncompatibleAPIVersionError(ExportFlowError):
+    """The server speaks a different major version of the API than this SDK."""
+
+
+class SignatureVerificationError(ExportFlowError):
+    """A webhook's signature did not verify. Do not trust the payload."""
+
+
+class WaitTimeoutError(ExportFlowError):
+    """A ``wait`` helper gave up before the work finished. The work continues;
+    fetch the resource later or use a webhook."""
+
+
+class ProcessingFailedError(ExportFlowError):
+    """A document's processing or a verification ended in failure."""
+
+    def __init__(self, message: str, *, resource_id: str) -> None:
+        super().__init__(message)
+        self.resource_id = resource_id

exportflow/_models.py

@@ -0,0 +1,305 @@
+"""What the API returns, as plain typed objects.
+
+Each model is built from the JSON by name and ignores fields it does not know.
+That is deliberate: within a major version the API only ever adds fields, so
+an SDK released today keeps working when the API grows tomorrow. The whole
+response is kept on ``.raw`` for anything newer than this SDK.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime as dt
+from typing import Any, Dict, List, Mapping, Optional, Type, TypeVar
+
+__all__ = [
+    "Document",
+    "ExtractedField",
+    "Extraction",
+    "Finding",
+    "Identity",
+    "MeterUsage",
+    "ProcessingAccepted",
+    "Reading",
+    "Record",
+    "RecordField",
+    "Shipment",
+    "Usage",
+    "Verification",
+    "WebhookEndpoint",
+    "WebhookEvent",
+]
+
+T = TypeVar("T", bound="_Model")
+
+
+def _moment(value: Any) -> Optional[dt.datetime]:
+    if not value:
+        return None
+    return dt.datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+
+
+def _day(value: Any) -> Optional[dt.date]:
+    return dt.date.fromisoformat(str(value)) if value else None
+
+
+@dataclasses.dataclass(frozen=True)
+class _Model:
+    raw: Mapping[str, Any] = dataclasses.field(repr=False, compare=False)
+
+    @classmethod
+    def _build(cls: Type[T], data: Mapping[str, Any]) -> T:
+        known = {f.name: f for f in dataclasses.fields(cls) if f.name != "raw"}
+        values: Dict[str, Any] = {}
+        for name, field in known.items():
+            value = data.get(name)
+            if name.endswith(("_at",)) or name in ("created_at", "uploaded_at"):
+                value = _moment(value)
+            elif name in ("period_start", "period_end"):
+                value = _day(value)
+            if value is None and field.default is not dataclasses.MISSING:
+                value = field.default
+            elif value is None and field.default_factory is not dataclasses.MISSING:  # type: ignore[misc]
+                value = field.default_factory()  # type: ignore[misc]
+            values[name] = value
+        return cls(raw=data, **values)
+
+
+@dataclasses.dataclass(frozen=True)
+class Identity(_Model):
+    organisation_id: str = ""
+    organisation_name: str = ""
+    application_id: str = ""
+    application_name: str = ""
+    environment: str = ""
+    key_prefix: str = ""
+    scopes: List[str] = dataclasses.field(default_factory=list)
+    api_version: str = ""
+
+
+@dataclasses.dataclass(frozen=True)
+class Shipment(_Model):
+    id: str = ""
+    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
+    environment: str = ""
+    created_at: Optional[dt.datetime] = None
+
+
+@dataclasses.dataclass(frozen=True)
+class Document(_Model):
+    id: str = ""
+    shipment_id: str = ""
+    filename: Optional[str] = None
+    media_type: str = ""
+    sha256: str = ""
+    page_count: Optional[int] = None
+    document_type: Optional[str] = None
+    declared_type: Optional[str] = None
+    detected_type: Optional[str] = None
+    type_confidence: Optional[float] = None
+    status: str = ""
+    error: Optional[str] = None
+    parent_document_id: Optional[str] = None
+    duplicate: bool = False
+    uploaded_at: Optional[dt.datetime] = None
+
+    @property
+    def is_finished(self) -> bool:
+        """True once processing has ended, successfully or not."""
+        return self.status in ("processed", "failed", "split")
+
+
+@dataclasses.dataclass(frozen=True)
+class ProcessingAccepted(_Model):
+    document_id: str = ""
+    status: str = ""
+    queued: bool = False
+
+
+@dataclasses.dataclass(frozen=True)
+class ExtractedField(_Model):
+    name: str = ""
+    value: Optional[str] = None
+    unavailable_reason: Optional[str] = None
+    confidence: Optional[float] = None
+    page: Optional[int] = None
+    method: str = ""
+    extraction_id: str = ""
+
+
+@dataclasses.dataclass(frozen=True)
+class Extraction(_Model):
+    document_id: str = ""
+    status: str = ""
+    document_type: Optional[str] = None
+    fields: List[ExtractedField] = dataclasses.field(default_factory=list)
+
+    @classmethod
+    def _build(cls, data: Mapping[str, Any]) -> "Extraction":
+        built = super()._build(data)
+        return dataclasses.replace(
+            built, fields=[ExtractedField._build(item) for item in data.get("fields") or []]
+        )
+
+    def value(self, name: str) -> Optional[str]:
+        """The value read for ``name``, or None if it was not read."""
+        for field in self.fields:
+            if field.name == name and field.value is not None:
+                return field.value
+        return None
+
+    def as_dict(self) -> Dict[str, Optional[str]]:
+        """``{field name: value}`` for every field that has a value."""
+        return {f.name: f.value for f in self.fields if f.value is not None}
+
+
+@dataclasses.dataclass(frozen=True)
+class Reading(_Model):
+    document_id: str = ""
+    value: Optional[str] = None
+    unavailable_reason: Optional[str] = None
+    extraction_id: str = ""
+
+
+@dataclasses.dataclass(frozen=True)
+class RecordField(_Model):
+    name: str = ""
+    readings: List[Reading] = dataclasses.field(default_factory=list)
+    confirmed_value: Optional[str] = None
+    confirmed_absence: Optional[str] = None
+    confirmed_at: Optional[dt.datetime] = None
+
+    @classmethod
+    def _build(cls, data: Mapping[str, Any]) -> "RecordField":
+        built = super()._build(data)
+        return dataclasses.replace(
+            built, readings=[Reading._build(item) for item in data.get("readings") or []]
+        )
+
+    @property
+    def distinct_values(self) -> List[str]:
+        """The different values the documents give. More than one is a
+        disagreement between documents."""
+        return sorted({r.value for r in self.readings if r.value is not None})
+
+
+@dataclasses.dataclass(frozen=True)
+class Record(_Model):
+    shipment_id: str = ""
+    confirmed: bool = False
+    fields: List[RecordField] = dataclasses.field(default_factory=list)
+
+    @classmethod
+    def _build(cls, data: Mapping[str, Any]) -> "Record":
+        built = super()._build(data)
+        return dataclasses.replace(
+            built, fields=[RecordField._build(item) for item in data.get("fields") or []]
+        )
+
+
+@dataclasses.dataclass(frozen=True)
+class Finding(_Model):
+    id: str = ""
+    rule: str = ""
+    rule_version: int = 0
+    severity: str = ""
+    document_id: Optional[str] = None
+    field: Optional[str] = None
+    found: Optional[str] = None
+    expected: Optional[str] = None
+    message: str = ""
+
+
+@dataclasses.dataclass(frozen=True)
+class Verification(_Model):
+    id: str = ""
+    shipment_id: str = ""
+    status: str = ""
+    rule_set_version: Optional[int] = None
+    severity_counts: Dict[str, int] = dataclasses.field(default_factory=dict)
+    failure_reason: Optional[str] = None
+    created_at: Optional[dt.datetime] = None
+    completed_at: Optional[dt.datetime] = None
+    coverage: Optional[Dict[str, Any]] = None
+    findings: List[Finding] = dataclasses.field(default_factory=list)
+
+    @classmethod
+    def _build(cls, data: Mapping[str, Any]) -> "Verification":
+        built = super()._build(data)
+        return dataclasses.replace(
+            built, findings=[Finding._build(item) for item in data.get("findings") or []]
+        )
+
+    @property
+    def is_finished(self) -> bool:
+        return self.status in ("complete", "failed")
+
+
+@dataclasses.dataclass(frozen=True)
+class MeterUsage(_Model):
+    meter: str = ""
+    name: str = ""
+    unit: str = ""
+    succeeded: int = 0
+    failed: int = 0
+    billable_units: int = 0
+    estimated_charge_micro: int = 0
+    quota: Optional[int] = None
+
+
+@dataclasses.dataclass(frozen=True)
+class Usage(_Model):
+    environment: str = ""
+    period_start: Optional[dt.date] = None
+    period_end: Optional[dt.date] = None
+    currency: str = ""
+    plan: str = ""
+    meters: List[MeterUsage] = dataclasses.field(default_factory=list)
+    estimated_charge_micro: int = 0
+
+    @classmethod
+    def _build(cls, data: Mapping[str, Any]) -> "Usage":
+        built = super()._build(data)
+        return dataclasses.replace(
+            built, meters=[MeterUsage._build(item) for item in data.get("meters") or []]
+        )
+
+    @property
+    def estimated_charge(self) -> float:
+        """The estimate in whole units of ``currency``, for display."""
+        return self.estimated_charge_micro / 1_000_000
+
+
+@dataclasses.dataclass(frozen=True)
+class WebhookEndpoint(_Model):
+    id: str = ""
+    application_id: str = ""
+    url: str = ""
+    description: Optional[str] = None
+    event_types: List[str] = dataclasses.field(default_factory=list)
+    status: str = ""
+    disabled_reason: Optional[str] = None
+    created_at: Optional[dt.datetime] = None
+    last_success_at: Optional[dt.datetime] = None
+    last_failure_at: Optional[dt.datetime] = None
+    signing_secret: Optional[str] = None
+    """Present only on the endpoint returned by ``create``. Store it."""
+
+
+@dataclasses.dataclass(frozen=True)
+class WebhookEvent(_Model):
+    """A verified webhook delivery."""
+
+    id: str = ""
+    type: str = ""
+    created_at: Optional[dt.datetime] = None
+    api_version: str = ""
+    environment: str = ""
+    application_id: Optional[str] = None
+    data: Dict[str, Any] = dataclasses.field(default_factory=dict)

exportflow/_version.py

@@ -0,0 +1,11 @@
+"""The SDK's version, and the API version it was built for."""
+
+__version__ = "1.0.0"
+
+API_MAJOR_VERSION = 1
+"""The major version of the ExportFlow API this SDK speaks (``/public/v1``).
+
+The server states its version on every response. A server on a different
+major version is a different contract, and the SDK says so instead of
+guessing at fields that may have changed meaning.
+"""

exportflow/webhooks.py

@@ -0,0 +1,87 @@
+"""Verifying webhooks.
+
+ExportFlow signs every delivery with your endpoint's signing secret. Verify
+the signature before you trust the payload: the URL of a webhook endpoint is
+not a secret, and anybody who learns it can post to it.
+
+    from exportflow import webhooks
+
+    event = webhooks.construct_event(
+        payload=request.body,                       # the raw bytes, not parsed JSON
+        signature=request.headers["ExportFlow-Signature"],
+        secret=os.environ["EXPORTFLOW_WEBHOOK_SECRET"],
+    )
+    if event.type == "document.processing.completed":
+        ...
+
+Deliveries are at least once: the same event can arrive twice. ``event.id`` is
+the same both times; record the ids you have handled and skip a repeat.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Optional, Union
+
+from ._errors import SignatureVerificationError
+from ._models import WebhookEvent
+
+__all__ = ["SIGNATURE_HEADER", "TOLERANCE_SECONDS", "construct_event", "sign", "verify"]
+
+SIGNATURE_HEADER = "ExportFlow-Signature"
+TOLERANCE_SECONDS = 300
+"""A delivery older than this is refused, so a captured one cannot be replayed."""
+
+
+def _bytes(payload: Union[bytes, str]) -> bytes:
+    return payload.encode("utf-8") if isinstance(payload, str) else bytes(payload)
+
+
+def sign(secret: str, payload: Union[bytes, str], *, timestamp: int) -> str:
+    """The header ExportFlow would send for this payload. Useful in your tests."""
+    mac = hmac.new(
+        secret.encode("utf-8"), f"{timestamp}.".encode() + _bytes(payload), hashlib.sha256
+    )
+    return f"t={timestamp},v1={mac.hexdigest()}"
+
+
+def verify(
+    payload: Union[bytes, str],
+    signature: str,
+    secret: str,
+    *,
+    tolerance: int = TOLERANCE_SECONDS,
+    now: Optional[float] = None,
+) -> bool:
+    """True if ``signature`` is ExportFlow's signature of ``payload``, made
+    within ``tolerance`` seconds of now. Never raises for a bad signature."""
+    parts = dict(part.split("=", 1) for part in (signature or "").split(",") if "=" in part)
+    try:
+        timestamp = int(parts.get("t", ""))
+    except ValueError:
+        return False
+    current = time.time() if now is None else now
+    if abs(current - timestamp) > tolerance:
+        return False
+    expected = sign(secret, payload, timestamp=timestamp).split("v1=", 1)[1]
+    return hmac.compare_digest(expected, parts.get("v1", ""))
+
+
+def construct_event(
+    payload: Union[bytes, str],
+    signature: str,
+    secret: str,
+    *,
+    tolerance: int = TOLERANCE_SECONDS,
+) -> WebhookEvent:
+    """Verify a delivery and return the event, or raise
+    :class:`~exportflow.SignatureVerificationError`."""
+    if not verify(payload, signature, secret, tolerance=tolerance):
+        raise SignatureVerificationError(
+            "The webhook signature did not verify. Check that the payload is the raw "
+            "request body and that the secret belongs to this endpoint."
+        )
+    return WebhookEvent._build(json.loads(_bytes(payload)))