scanii-python 1.0.0__py3-none-any.whl

scanii/__init__.py

@@ -0,0 +1,30 @@
+"""Scanii Python SDK — zero-dependency client for the Scanii content security API.
+
+See https://scanii.github.io/openapi/v22/ for the full API reference.
+"""
+
+from scanii._version import __version__
+from scanii.client import ScaniiClient
+from scanii.errors import ScaniiAuthError, ScaniiError, ScaniiRateLimitError
+from scanii.models import (
+    ScaniiAuthToken,
+    ScaniiPendingResult,
+    ScaniiProcessingResult,
+    ScaniiTraceEvent,
+    ScaniiTraceResult,
+)
+from scanii.target import ScaniiTarget
+
+__all__ = [
+    "__version__",
+    "ScaniiClient",
+    "ScaniiTarget",
+    "ScaniiProcessingResult",
+    "ScaniiPendingResult",
+    "ScaniiAuthToken",
+    "ScaniiTraceResult",
+    "ScaniiTraceEvent",
+    "ScaniiError",
+    "ScaniiAuthError",
+    "ScaniiRateLimitError",
+]

scanii/_multipart.py

@@ -0,0 +1,199 @@
+"""Hand-rolled multipart/form-data encoder (RFC 7578).
+
+Internal module — underscore-prefixed, not part of the public API.
+
+The encoder is stream-first: when a file_obj is provided it builds a
+:class:`_ChainedIO` that chains prologue bytes + the caller's IO + epilogue
+bytes without reading the file body at construction time. The file content is
+only read when urllib reads from the chained stream on the wire.
+
+Mirrors the approach of scanii-ruby's Multipart::ChainedIO and
+scanii-rust's prologue/epilogue pattern.
+"""
+
+from __future__ import annotations
+
+import io
+import mimetypes
+import os
+import secrets
+import tempfile
+from typing import IO, cast
+
+
+def _make_boundary() -> str:
+    return f"----scanii-python-boundary-{secrets.token_hex(16)}"
+
+
+def _guess_content_type(filename: str) -> str:
+    ct, _ = mimetypes.guess_type(filename)
+    return ct or "application/octet-stream"
+
+
+def _io_remaining_bytes(file_obj: IO[bytes]) -> int | None:
+    """Return the number of bytes remaining to be read from file_obj, or None.
+
+    Tries three strategies in order:
+    1. ``fileno()`` + ``os.fstat`` — most reliable for real files.
+    2. ``getvalue()`` — works for in-memory :class:`io.BytesIO` and
+       :class:`tempfile.SpooledTemporaryFile` when still in RAM.
+    3. ``seek``/``tell`` — works for any seekable IO; restores position.
+
+    Returns ``None`` when all three fail (pipes, generators, sockets).
+    """
+    # Strategy 1 — real files with an OS file descriptor
+    try:
+        fd = file_obj.fileno()
+        size = os.fstat(fd).st_size
+        pos = file_obj.tell()
+        return size - pos
+    except (AttributeError, io.UnsupportedOperation, OSError):
+        pass
+
+    # Strategy 2 — BytesIO / in-memory SpooledTemporaryFile
+    try:
+        val: bytes = file_obj.getvalue()  # type: ignore[attr-defined]
+        pos = file_obj.tell()
+        return len(val) - pos
+    except AttributeError:
+        pass
+
+    # Strategy 3 — any seekable IO
+    try:
+        pos = file_obj.tell()
+        file_obj.seek(0, 2)
+        end = file_obj.tell()
+        file_obj.seek(pos)
+        return end - pos
+    except (AttributeError, OSError, io.UnsupportedOperation):
+        pass
+
+    return None
+
+
+class _ChainedIO:
+    """Sequential reader over a list of IO parts.
+
+    Reads from parts[0] until exhausted, then parts[1], etc. — without
+    reading any part at construction time. Used to chain prologue bytes +
+    a caller-supplied file IO + epilogue bytes so the file body is only
+    read when urllib transfers bytes to the socket.
+
+    Mirrors Ruby's ``Scanii::Multipart::ChainedIO``.
+    """
+
+    def __init__(self, parts: list[IO[bytes]]) -> None:
+        self._parts = parts
+        self._idx = 0
+
+    def read(self, n: int = -1) -> bytes:
+        if n < 0:
+            return self._read_all()
+        return self._read_n(n)
+
+    def _read_all(self) -> bytes:
+        chunks: list[bytes] = []
+        while self._idx < len(self._parts):
+            chunk = self._parts[self._idx].read()
+            if chunk:
+                chunks.append(chunk)
+            self._idx += 1
+        return b"".join(chunks)
+
+    def _read_n(self, n: int) -> bytes:
+        if n == 0:
+            return b""
+        chunks: list[bytes] = []
+        remaining = n
+        while remaining > 0 and self._idx < len(self._parts):
+            chunk = self._parts[self._idx].read(remaining)
+            if chunk:
+                chunks.append(chunk)
+                remaining -= len(chunk)
+            else:
+                self._idx += 1
+        return b"".join(chunks)
+
+
+def encode(
+    fields: dict[str, str],
+    file_obj: IO[bytes] | None = None,
+    filename: str | None = None,
+    content_type: str | None = None,
+) -> tuple[IO[bytes], str, int]:
+    """Encode a multipart/form-data body.
+
+    **File mode** (``file_obj`` provided): returns a :class:`_ChainedIO` that
+    streams prologue bytes → file body → epilogue bytes without reading the
+    file at construction time. The caller's IO is only read when urllib reads
+    from the returned stream. Paths and ``BytesIO`` get true socket-level
+    streaming; IOs without ``fileno()`` or ``seek``/``tell`` fall back to a
+    ``SpooledTemporaryFile(max_size=1 MiB)`` — small payloads stay in memory,
+    larger ones spill to disk.
+
+    **Fields-only mode** (``file_obj=None``): returns an ``io.BytesIO``
+    containing a multipart body with no file part. Used by
+    ``process_from_url``.
+
+    Returns ``(body_stream, content_type_header, content_length)``.
+    """
+    boundary = _make_boundary()
+    ct_header = f"multipart/form-data; boundary={boundary}"
+
+    # Build text-field parts (same for both modes)
+    text_bytes: list[bytes] = []
+    for name, value in fields.items():
+        text_bytes.append(
+            (
+                f"--{boundary}\r\n"
+                f'Content-Disposition: form-data; name="{name}"\r\n'
+                f"Content-Type: text/plain; charset=UTF-8\r\n"
+                f"\r\n"
+                f"{value}\r\n"
+            ).encode("utf-8")
+        )
+
+    if file_obj is None:
+        # Fields-only mode — closing boundary with no file part
+        text_bytes.append(f"--{boundary}--\r\n".encode("utf-8"))
+        body = b"".join(text_bytes)
+        return io.BytesIO(body), ct_header, len(body)
+
+    # File mode — stream prologue + file + epilogue
+    if filename is None:
+        raise ValueError("filename is required when file_obj is provided")
+
+    ct = content_type or _guess_content_type(filename)
+    prologue = b"".join(text_bytes) + (
+        f"--{boundary}\r\n"
+        f'Content-Disposition: form-data; name="file"; filename="{filename}"\r\n'
+        f"Content-Type: {ct}\r\n"
+        f"\r\n"
+    ).encode("utf-8")
+    # Epilogue: CRLF closes the file data part, then the final boundary.
+    epilogue = b"\r\n" + f"--{boundary}--\r\n".encode("utf-8")
+
+    # Determine file size without reading the body
+    file_size = _io_remaining_bytes(file_obj)
+
+    if file_size is None:
+        # Size-indeterminate IO (pipes, sockets, generators) — buffer via
+        # SpooledTemporaryFile so we can compute length and still stream.
+        spooled: tempfile.SpooledTemporaryFile[bytes] = tempfile.SpooledTemporaryFile(
+            max_size=1024 * 1024
+        )
+        buf = file_obj.read(65536)
+        while buf:
+            spooled.write(buf)
+            buf = file_obj.read(65536)
+        spooled.seek(0)
+        file_size = _io_remaining_bytes(cast(IO[bytes], spooled))
+        if file_size is None:
+            spooled.seek(0, 2)
+            file_size = spooled.tell()
+            spooled.seek(0)
+        file_obj = cast(IO[bytes], spooled)
+
+    total_length = len(prologue) + file_size + len(epilogue)
+    chained = _ChainedIO([io.BytesIO(prologue), file_obj, io.BytesIO(epilogue)])
+    return cast(IO[bytes], chained), ct_header, total_length

scanii/_version.py

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

scanii/client.py

@@ -0,0 +1,460 @@
+"""Scanii SDK client."""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import IO
+
+from scanii._multipart import encode as _multipart_encode
+from scanii._version import __version__
+from scanii.errors import ScaniiAuthError, ScaniiError, ScaniiRateLimitError
+from scanii.models import (
+    ScaniiAuthToken,
+    ScaniiPendingResult,
+    ScaniiProcessingResult,
+    ScaniiTraceResult,
+)
+from scanii.target import ScaniiTarget
+
+_API_VERSION = "/v2.2"
+
+
+class ScaniiClient:
+    """Synchronous client for the Scanii REST API v2.2.
+
+    Construct with either ``key`` + ``secret`` (HTTP Basic Auth) or ``token``
+    (auth-token authentication). Mixing the two raises ``ValueError``.
+
+    ``target`` is required — choose a regional constant for production or
+    construct a custom ``ScaniiTarget`` for local testing::
+
+        client = ScaniiClient(key="your-key", secret="your-secret", target=ScaniiTarget.US1)
+
+    Per SDK Principle 3 the client is integration-only: it does not retry,
+    batch, or paginate. Each public method maps to exactly one HTTP request.
+
+    See https://scanii.github.io/openapi/v22/
+    """
+
+    def __init__(
+        self,
+        *,
+        key: str | None = None,
+        secret: str | None = None,
+        token: str | None = None,
+        target: ScaniiTarget | None = None,
+        timeout: float = 60.0,
+    ) -> None:
+        if not isinstance(target, ScaniiTarget):
+            raise TypeError(
+                "ScaniiClient requires a ScaniiTarget for data residency compliance. Examples:\n"
+                "  ScaniiClient(key=..., secret=..., target=ScaniiTarget.US1)\n"
+                "  ScaniiClient(key=..., secret=..., target=ScaniiTarget.EU1)\n"
+                "For local testing against scanii-cli:\n"
+                '  ScaniiClient(key=..., secret=..., target=ScaniiTarget("http://localhost:4000"))\n'
+                "Available regional constants: US1, EU1, EU2, AP1, AP2, CA1."
+            )
+        self._auth_header = self._build_auth_header(key, secret, token)
+        self._target = target
+        self._timeout = float(timeout)
+        self._user_agent = f"scanii-python/{__version__}"
+
+    # ------------------------------------------------------------------
+    # File scanning — stream-first
+    # ------------------------------------------------------------------
+
+    def process(
+        self,
+        content: IO[bytes],
+        filename: str,
+        content_type: str | None = None,
+        metadata: dict[str, str] | None = None,
+        callback: str | None = None,
+    ) -> ScaniiProcessingResult:
+        """Submit an IO-like object for synchronous scanning.
+
+        ``content`` is duck-typed: anything with ``read(n) -> bytes``.
+        Both ``open(path, 'rb')`` and ``io.BytesIO(...)`` work.
+
+        :param content: IO-like object (anything with ``read(n) -> bytes``)
+        :param filename: filename sent in the multipart part
+        :param content_type: content-type of the file part; guessed from filename when None
+        :param metadata: arbitrary key/value pairs attached to the result
+        :param callback: URL to POST the result to on completion
+        :see: https://scanii.github.io/openapi/v22/ POST /files
+        :return: :class:`~scanii.ScaniiProcessingResult`
+        """
+        fields = self._build_fields(metadata, callback)
+        body_stream, ct, content_length = _multipart_encode(
+            fields, file_obj=content, filename=filename, content_type=content_type
+        )
+        status, resp_body, headers = self._post(
+            "/files", body=body_stream, content_type=ct, content_length=content_length
+        )
+        self._raise_for_status(status, resp_body, headers, expected=201)
+        return ScaniiProcessingResult.from_response(resp_body, headers)
+
+    def process_file(
+        self,
+        path: str | os.PathLike[str],
+        metadata: dict[str, str] | None = None,
+        callback: str | None = None,
+    ) -> ScaniiProcessingResult:
+        """Submit a file path for synchronous scanning.
+
+        Opens the file in binary mode, streams it to Scanii, and closes it.
+        Delegates to :meth:`process` with ``filename`` set to the basename.
+
+        :param path: path to the file to upload
+        :param metadata: arbitrary key/value pairs attached to the result
+        :param callback: URL to POST the result to on completion
+        :see: https://scanii.github.io/openapi/v22/ POST /files
+        :return: :class:`~scanii.ScaniiProcessingResult`
+        """
+        path = os.fspath(path)
+        with open(path, "rb") as f:
+            return self.process(f, filename=os.path.basename(path),
+                                metadata=metadata, callback=callback)
+
+    def process_async(
+        self,
+        content: IO[bytes],
+        filename: str,
+        content_type: str | None = None,
+        metadata: dict[str, str] | None = None,
+        callback: str | None = None,
+    ) -> ScaniiPendingResult:
+        """Submit an IO-like object for server-side asynchronous scanning.
+
+        Returns a pending id; the final result is delivered to ``callback``
+        (when supplied) or fetched via :meth:`retrieve`.
+
+        :param content: IO-like object (anything with ``read(n) -> bytes``)
+        :param filename: filename sent in the multipart part
+        :param content_type: content-type of the file part; guessed from filename when None
+        :param metadata: arbitrary key/value pairs attached to the result
+        :param callback: URL to POST the result to on completion
+        :see: https://scanii.github.io/openapi/v22/ POST /files/async
+        :return: :class:`~scanii.ScaniiPendingResult`
+        """
+        fields = self._build_fields(metadata, callback)
+        body_stream, ct, content_length = _multipart_encode(
+            fields, file_obj=content, filename=filename, content_type=content_type
+        )
+        status, resp_body, headers = self._post(
+            "/files/async", body=body_stream, content_type=ct, content_length=content_length
+        )
+        self._raise_for_status(status, resp_body, headers, expected=202)
+        return ScaniiPendingResult.from_response(resp_body, headers)
+
+    def process_async_file(
+        self,
+        path: str | os.PathLike[str],
+        metadata: dict[str, str] | None = None,
+        callback: str | None = None,
+    ) -> ScaniiPendingResult:
+        """Submit a file path for server-side asynchronous scanning.
+
+        Opens the file in binary mode and delegates to :meth:`process_async`.
+
+        :param path: path to the file to upload
+        :param metadata: arbitrary key/value pairs attached to the result
+        :param callback: URL to POST the result to on completion
+        :see: https://scanii.github.io/openapi/v22/ POST /files/async
+        :return: :class:`~scanii.ScaniiPendingResult`
+        """
+        path = os.fspath(path)
+        with open(path, "rb") as f:
+            return self.process_async(f, filename=os.path.basename(path),
+                                      metadata=metadata, callback=callback)
+
+    # ------------------------------------------------------------------
+    # v2.2 surface
+    # ------------------------------------------------------------------
+
+    def retrieve_trace(self, id: str) -> ScaniiTraceResult | None:
+        """Retrieve the processing event trace for a previously submitted scan.
+
+        Returns ``None`` when no trace exists for the given id (HTTP 404).
+
+        This is a v2.2 preview surface; the API shape may shift before it is
+        marked stable.
+
+        :param id: processing id returned by :meth:`process` or :meth:`process_file`
+        :see: https://scanii.github.io/openapi/v22/ GET /files/{id}/trace
+        :return: :class:`~scanii.ScaniiTraceResult` or ``None``
+        """
+        if not id:
+            raise ValueError("id must not be empty")
+        status, resp_body, headers = self._request("GET", f"/files/{_urlencode(id)}/trace")
+        if status == 404:
+            return None
+        self._raise_for_status(status, resp_body, headers, expected=200)
+        return ScaniiTraceResult.from_response(resp_body, headers)
+
+    def process_from_url(
+        self,
+        location: str,
+        callback: str | None = None,
+        metadata: dict[str, str] | None = None,
+    ) -> ScaniiProcessingResult:
+        """Submit a remote URL for synchronous scanning.
+
+        Sends the URL as a ``location`` field in a ``multipart/form-data`` POST
+        to ``/files``. The Scanii server fetches and scans the URL synchronously
+        and returns a :class:`~scanii.ScaniiProcessingResult`. This is distinct
+        from :meth:`fetch`, which submits to ``/files/fetch`` for asynchronous
+        server-side fetching.
+
+        ``location`` must be a string URL — matches the existing :meth:`fetch`
+        string-URL convention and the Java reference (``processFromUrl(String)``).
+
+        This is a v2.2 preview surface; the API shape may shift before it is
+        marked stable.
+
+        :param location: URL of the content to scan
+        :param callback: URL to POST the result to on completion
+        :param metadata: arbitrary key/value pairs attached to the result
+        :see: https://scanii.github.io/openapi/v22/ POST /files
+        :return: :class:`~scanii.ScaniiProcessingResult`
+        """
+        if not location:
+            raise ValueError("location must not be empty")
+        fields = self._build_fields(metadata, callback)
+        fields["location"] = location
+        # Fields-only multipart — POST /v2.2/files rejects urlencoded on this endpoint.
+        body_stream, ct, content_length = _multipart_encode(fields)
+        status, resp_body, headers = self._post(
+            "/files", body=body_stream, content_type=ct, content_length=content_length
+        )
+        self._raise_for_status(status, resp_body, headers, expected=201)
+        return ScaniiProcessingResult.from_response(resp_body, headers)
+
+    # ------------------------------------------------------------------
+    # Other API methods
+    # ------------------------------------------------------------------
+
+    def fetch(
+        self,
+        url: str,
+        metadata: dict[str, str] | None = None,
+        callback: str | None = None,
+    ) -> ScaniiPendingResult:
+        """Ask Scanii to download a remote URL and scan it asynchronously.
+
+        :see: https://scanii.github.io/openapi/v22/ POST /files/fetch
+        :return: :class:`~scanii.ScaniiPendingResult`
+        """
+        if not url:
+            raise ValueError("url must not be empty")
+        form: dict[str, str] = {"location": url}
+        if callback:
+            form["callback"] = callback
+        for k, v in (metadata or {}).items():
+            form[f"metadata[{k}]"] = str(v)
+        body = urllib.parse.urlencode(form).encode("utf-8")
+        status, resp_body, headers = self._post(
+            "/files/fetch", body=body,
+            content_type="application/x-www-form-urlencoded"
+        )
+        self._raise_for_status(status, resp_body, headers, expected=202)
+        return ScaniiPendingResult.from_response(resp_body, headers)
+
+    def retrieve(self, id: str) -> ScaniiProcessingResult:
+        """Retrieve a previously submitted scan result by id.
+
+        :see: https://scanii.github.io/openapi/v22/ GET /files/{id}
+        :return: :class:`~scanii.ScaniiProcessingResult`
+        """
+        if not id:
+            raise ValueError("id must not be empty")
+        status, resp_body, headers = self._request("GET", f"/files/{_urlencode(id)}")
+        self._raise_for_status(status, resp_body, headers, expected=200)
+        return ScaniiProcessingResult.from_response(resp_body, headers)
+
+    def ping(self) -> bool:
+        """Verify that the configured credentials reach the API.
+
+        :see: https://scanii.github.io/openapi/v22/ GET /ping
+        :return: ``True`` when the API responds 200
+        :raises ScaniiAuthError: when credentials are rejected
+        """
+        status, resp_body, headers = self._request("GET", "/ping")
+        if status == 200:
+            return True
+        self._raise_for_status(status, resp_body, headers, expected=200)
+        return False  # unreachable; keeps type checker happy
+
+    def create_auth_token(self, timeout_seconds: int) -> ScaniiAuthToken:
+        """Mint a short-lived auth token.
+
+        ``timeout_seconds`` must be a positive integer.
+
+        :see: https://scanii.github.io/openapi/v22/ POST /auth/tokens
+        :return: :class:`~scanii.ScaniiAuthToken`
+        """
+        ts = int(timeout_seconds)
+        if ts <= 0:
+            raise ValueError("timeout_seconds must be positive")
+        body = urllib.parse.urlencode({"timeout": ts}).encode("utf-8")
+        status, resp_body, headers = self._post(
+            "/auth/tokens", body=body,
+            content_type="application/x-www-form-urlencoded"
+        )
+        if status not in (200, 201):
+            self._raise_for_status(status, resp_body, headers, expected=201)
+        return ScaniiAuthToken.from_response(resp_body, headers)
+
+    def retrieve_auth_token(self, id: str) -> ScaniiAuthToken:
+        """Inspect a previously created auth token.
+
+        :see: https://scanii.github.io/openapi/v22/ GET /auth/tokens/{id}
+        :return: :class:`~scanii.ScaniiAuthToken`
+        """
+        if not id:
+            raise ValueError("id must not be empty")
+        status, resp_body, headers = self._request("GET", f"/auth/tokens/{_urlencode(id)}")
+        self._raise_for_status(status, resp_body, headers, expected=200)
+        return ScaniiAuthToken.from_response(resp_body, headers)
+
+    def delete_auth_token(self, id: str) -> bool:
+        """Revoke an auth token.
+
+        :see: https://scanii.github.io/openapi/v22/ DELETE /auth/tokens/{id}
+        :return: ``True`` on success (HTTP 204)
+        """
+        if not id:
+            raise ValueError("id must not be empty")
+        status, resp_body, headers = self._request("DELETE", f"/auth/tokens/{_urlencode(id)}")
+        self._raise_for_status(status, resp_body, headers, expected=204)
+        return True
+
+    # ------------------------------------------------------------------
+    # Private helpers
+    # ------------------------------------------------------------------
+
+    def _build_auth_header(
+        self, key: str | None, secret: str | None, token: str | None
+    ) -> str:
+        if token:
+            if key or secret:
+                raise ValueError("supply either token or key+secret, not both")
+            credentials = base64.b64encode(f"{token}:".encode("utf-8")).decode("ascii")
+            return f"Basic {credentials}"
+        if not key:
+            raise ValueError("key must be set (or use token for auth-token mode)")
+        if ":" in key:
+            raise ValueError("key must not contain a colon")
+        if not secret:
+            raise ValueError("secret must be set when using key auth")
+        credentials = base64.b64encode(f"{key}:{secret}".encode("utf-8")).decode("ascii")
+        return f"Basic {credentials}"
+
+    def _build_fields(
+        self, metadata: dict[str, str] | None, callback: str | None
+    ) -> dict[str, str]:
+        fields: dict[str, str] = {}
+        for k, v in (metadata or {}).items():
+            fields[f"metadata[{k}]"] = str(v)
+        if callback:
+            fields["callback"] = callback
+        return fields
+
+    def _post(
+        self,
+        path: str,
+        body: bytes | IO[bytes],
+        content_type: str,
+        content_length: int | None = None,
+    ) -> tuple[int, str, dict[str, str]]:
+        return self._request(
+            "POST", path, body=body, content_type=content_type,
+            content_length=content_length
+        )
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        body: bytes | IO[bytes] | None = None,
+        content_type: str | None = None,
+        content_length: int | None = None,
+    ) -> tuple[int, str, dict[str, str]]:
+        url = self._target.resolve(_API_VERSION + path)
+        headers: dict[str, str] = {
+            "Authorization": self._auth_header,
+            "User-Agent": self._user_agent,
+            "Accept": "application/json",
+        }
+        if content_type:
+            headers["Content-Type"] = content_type
+        # Set Content-Length explicitly for stream bodies (urllib can't compute it).
+        # For bytes bodies urllib sets it automatically via len(); we leave that alone.
+        if content_length is not None:
+            headers["Content-Length"] = str(content_length)
+
+        req = urllib.request.Request(url, data=body, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+                resp_body = resp.read().decode("utf-8", errors="replace")
+                resp_headers = {k.lower(): v for k, v in resp.headers.items()}
+                return resp.status, resp_body, resp_headers
+        except urllib.error.HTTPError as e:
+            resp_body = e.read().decode("utf-8", errors="replace")
+            resp_headers = {k.lower(): v for k, v in e.headers.items()}
+            return e.code, resp_body, resp_headers
+        except urllib.error.URLError:
+            raise
+
+    def _raise_for_status(
+        self,
+        status: int,
+        body: str,
+        headers: dict[str, str],
+        *,
+        expected: int,
+    ) -> None:
+        if status == expected:
+            return
+        request_id = headers.get("x-scanii-request-id")
+        host_id = headers.get("x-scanii-host-id")
+        message = self._extract_error_message(body) or f"HTTP {status}"
+
+        if status in (401, 403):
+            raise ScaniiAuthError(
+                message, status_code=status, request_id=request_id,
+                host_id=host_id, body=body
+            )
+        if status == 429:
+            retry_after_raw = headers.get("retry-after")
+            retry_after = int(retry_after_raw) if retry_after_raw else None
+            raise ScaniiRateLimitError(
+                message, status_code=status, request_id=request_id,
+                host_id=host_id, body=body, retry_after=retry_after
+            )
+        raise ScaniiError(
+            message, status_code=status, request_id=request_id,
+            host_id=host_id, body=body
+        )
+
+    def _extract_error_message(self, body: str) -> str | None:
+        if not body:
+            return None
+        try:
+            decoded = json.loads(body)
+            if isinstance(decoded, dict):
+                error = decoded.get("error")
+                if isinstance(error, str):
+                    return error
+            return body
+        except (json.JSONDecodeError, ValueError):
+            return body
+
+
+def _urlencode(value: str) -> str:
+    return urllib.parse.quote(value, safe="")

scanii/errors.py

@@ -0,0 +1,47 @@
+"""Scanii SDK exception hierarchy."""
+
+from __future__ import annotations
+
+
+class ScaniiError(Exception):
+    """Base exception for all Scanii API errors.
+
+    Raised on HTTP 4xx/5xx responses. Carries the API-supplied message plus
+    optional diagnostic headers for support handoffs.
+
+    Per SDK Principle 3 (integration-only) the SDK does not retry on the
+    caller's behalf — backoff is the caller's responsibility.
+
+    See https://scanii.github.io/openapi/v22/
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        request_id: str | None = None,
+        host_id: str | None = None,
+        body: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.request_id = request_id
+        self.host_id = host_id
+        self.body = body
+
+
+class ScaniiAuthError(ScaniiError):
+    """Raised on HTTP 401 or 403 — credentials rejected by the API."""
+
+
+class ScaniiRateLimitError(ScaniiError):
+    """Raised on HTTP 429.
+
+    ``retry_after`` carries the value of the ``Retry-After`` response header in
+    seconds when the server provided one, otherwise ``None``.
+    """
+
+    def __init__(self, message: str, *, retry_after: int | None = None, **kwargs: object) -> None:
+        super().__init__(message, **kwargs)  # type: ignore[arg-type]
+        self.retry_after = retry_after

scanii/models.py

@@ -0,0 +1,177 @@
+"""Scanii SDK response model dataclasses."""
+
+from __future__ import annotations
+
+import json
+import warnings
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ScaniiTraceEvent:
+    """A single processing event in a scan trace.
+
+    See https://scanii.github.io/openapi/v22/
+    """
+
+    timestamp: str
+    message: str
+
+    @classmethod
+    def from_dict(cls, raw: dict[str, object]) -> "ScaniiTraceEvent":
+        return cls(
+            timestamp=str(raw.get("timestamp") or ""),
+            message=str(raw.get("message") or ""),
+        )
+
+
+@dataclass(frozen=True)
+class ScaniiTraceResult:
+    """Result of :meth:`~scanii.ScaniiClient.retrieve_trace`.
+
+    This is a v2.2 preview surface; the API shape may shift before it is
+    marked stable.
+
+    See https://scanii.github.io/openapi/v22/
+    """
+
+    resource_id: str
+    events: tuple[ScaniiTraceEvent, ...]
+    request_id: str | None
+    host_id: str | None
+
+    @classmethod
+    def from_response(cls, body: str, headers: dict[str, str]) -> "ScaniiTraceResult":
+        raw = json.loads(body) if body else {}
+        return cls(
+            resource_id=str(raw.get("id") or ""),
+            events=tuple(ScaniiTraceEvent.from_dict(e) for e in raw.get("events") or []),
+            request_id=headers.get("x-scanii-request-id"),
+            host_id=headers.get("x-scanii-host-id"),
+        )
+
+
+@dataclass(frozen=True)
+class ScaniiProcessingResult:
+    """Result of a synchronous scan returned by :meth:`~scanii.ScaniiClient.process`,
+    :meth:`~scanii.ScaniiClient.process_file`, :meth:`~scanii.ScaniiClient.process_from_url`,
+    and :meth:`~scanii.ScaniiClient.retrieve`.
+
+    ``findings`` is always a tuple. An empty tuple means the content is clean.
+
+    See https://scanii.github.io/openapi/v22/
+    """
+
+    id: str
+    findings: tuple[str, ...]
+    checksum: str | None
+    content_length: int | None
+    content_type: str | None
+    metadata: dict[str, str]
+    creation_date: str | None
+    request_id: str | None
+    host_id: str | None
+    resource_location: str | None
+    error: str | None = None
+    """
+    .. deprecated:: 1.0.0
+       Server-side errors arrive as :class:`~scanii.ScaniiError` subclasses on
+       non-2xx responses; this field is never populated on success.
+       Will be removed in a future major version.
+    """
+
+    def __post_init__(self) -> None:
+        if self.error is not None:
+            warnings.warn(
+                "ScaniiProcessingResult.error is deprecated and will be removed in a "
+                "future major version. Server-side errors arrive as ScaniiError "
+                "subclasses on non-2xx responses; this field is never populated on success.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
+    @classmethod
+    def from_response(cls, body: str, headers: dict[str, str]) -> "ScaniiProcessingResult":
+        raw = json.loads(body) if body else {}
+        return cls(
+            id=str(raw.get("id") or ""),
+            findings=tuple(str(f) for f in (raw.get("findings") or [])),
+            checksum=str(raw["checksum"]) if raw.get("checksum") is not None else None,
+            content_length=(
+                int(raw["content_length"]) if raw.get("content_length") is not None else None
+            ),
+            content_type=(
+                str(raw["content_type"]) if raw.get("content_type") is not None else None
+            ),
+            metadata={str(k): str(v) for k, v in (raw.get("metadata") or {}).items()},
+            creation_date=(
+                str(raw["creation_date"]) if raw.get("creation_date") is not None else None
+            ),
+            request_id=headers.get("x-scanii-request-id"),
+            host_id=headers.get("x-scanii-host-id"),
+            resource_location=headers.get("location"),
+            error=str(raw["error"]) if raw.get("error") is not None else None,
+        )
+
+
+@dataclass(frozen=True)
+class ScaniiPendingResult:
+    """Result of an asynchronous scan submission returned by
+    :meth:`~scanii.ScaniiClient.process_async`, :meth:`~scanii.ScaniiClient.process_async_file`,
+    and :meth:`~scanii.ScaniiClient.fetch`.
+
+    The actual scan result is fetched later via :meth:`~scanii.ScaniiClient.retrieve`
+    or delivered to the supplied callback URL.
+
+    See https://scanii.github.io/openapi/v22/
+    """
+
+    id: str
+    request_id: str | None
+    host_id: str | None
+    resource_location: str | None
+
+    @classmethod
+    def from_response(cls, body: str, headers: dict[str, str]) -> "ScaniiPendingResult":
+        raw = json.loads(body) if body else {}
+        return cls(
+            id=str(raw.get("id") or ""),
+            request_id=headers.get("x-scanii-request-id"),
+            host_id=headers.get("x-scanii-host-id"),
+            resource_location=headers.get("location"),
+        )
+
+
+@dataclass(frozen=True)
+class ScaniiAuthToken:
+    """Short-lived auth token returned by :meth:`~scanii.ScaniiClient.create_auth_token`
+    and :meth:`~scanii.ScaniiClient.retrieve_auth_token`.
+
+    Pass ``id`` as the ``token`` argument when constructing a :class:`~scanii.ScaniiClient`
+    to authenticate using the token instead of API key + secret.
+
+    See https://scanii.github.io/openapi/v22/
+    """
+
+    id: str
+    creation_date: str | None
+    expiration_date: str | None
+    request_id: str | None
+    host_id: str | None
+    resource_location: str | None
+
+    @classmethod
+    def from_response(cls, body: str, headers: dict[str, str]) -> "ScaniiAuthToken":
+        raw = json.loads(body) if body else {}
+        return cls(
+            id=str(raw.get("id") or ""),
+            creation_date=(
+                str(raw["creation_date"]) if raw.get("creation_date") is not None else None
+            ),
+            expiration_date=(
+                str(raw["expiration_date"]) if raw.get("expiration_date") is not None else None
+            ),
+            request_id=headers.get("x-scanii-request-id"),
+            host_id=headers.get("x-scanii-host-id"),
+            resource_location=headers.get("location"),
+        )

scanii/target.py

@@ -0,0 +1,62 @@
+"""Scanii regional API endpoints."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+from urllib.parse import urljoin
+
+
+class ScaniiTarget:
+    """
+    Scanii regional API endpoint.
+
+    Use one of the predefined regional constants (e.g. ``ScaniiTarget.US1``)
+    for production. The constructor accepts an arbitrary URL for testing
+    against scanii-cli or other local mocks::
+
+        target = ScaniiTarget("http://localhost:4000")
+
+    Note: ``ScaniiTarget.AUTO`` (latency-based routing) is intentionally
+    not provided. Customer data residency / chain-of-custody compliance
+    requires an explicit regional choice. Other Scanii SDKs that historically
+    defaulted to AUTO are being updated to deprecate it.
+    """
+
+    US1: ClassVar[ScaniiTarget]
+    EU1: ClassVar[ScaniiTarget]
+    EU2: ClassVar[ScaniiTarget]
+    AP1: ClassVar[ScaniiTarget]
+    AP2: ClassVar[ScaniiTarget]
+    CA1: ClassVar[ScaniiTarget]
+
+    def __init__(self, url: str) -> None:
+        if not url:
+            raise ValueError("ScaniiTarget URL must be a non-empty string")
+        self._url = url
+
+    @property
+    def endpoint(self) -> str:
+        """The base URL this target points at."""
+        return self._url
+
+    def resolve(self, path: str) -> str:
+        """Join the target's base URL with a request path."""
+        base = self._url if self._url.endswith("/") else self._url + "/"
+        return urljoin(base, path)
+
+    def __repr__(self) -> str:
+        return f"ScaniiTarget({self._url!r})"
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, ScaniiTarget) and self._url == other._url
+
+    def __hash__(self) -> int:
+        return hash(self._url)
+
+
+ScaniiTarget.US1 = ScaniiTarget("https://api-us1.scanii.com")
+ScaniiTarget.EU1 = ScaniiTarget("https://api-eu1.scanii.com")
+ScaniiTarget.EU2 = ScaniiTarget("https://api-eu2.scanii.com")
+ScaniiTarget.AP1 = ScaniiTarget("https://api-ap1.scanii.com")
+ScaniiTarget.AP2 = ScaniiTarget("https://api-ap2.scanii.com")
+ScaniiTarget.CA1 = ScaniiTarget("https://api-ca1.scanii.com")

scanii_python-1.0.0.dist-info/METADATA

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: scanii-python
+Version: 1.0.0
+Summary: Zero-dependency Python SDK for the Scanii content security API
+Project-URL: Homepage, https://scanii.com
+Project-URL: Repository, https://github.com/scanii/scanii-python
+Project-URL: Documentation, https://scanii.github.io/openapi/v22/
+Author: Scanii
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.13
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# scanii-python
+
+Python SDK for the [Scanii](https://scanii.com) content security API.
+
+## Installation
+
+```bash
+pip install scanii-python
+```
+
+Distribution name is `scanii-python`; import as `from scanii import ScaniiClient`.
+
+## SDK Principles
+
+1. **Light.** Zero runtime dependencies, stdlib only.
+2. **Up to date.** Always current with the latest Scanii API.
+3. **Integration-only.** Wraps the REST API — retries, concurrency, and batching are the caller's responsibility.
+
+## Quickstart
+
+```python
+from scanii import ScaniiClient, ScaniiTarget
+
+client = ScaniiClient(key="your-key", secret="your-secret", target=ScaniiTarget.US1)
+result = client.process_file("./document.pdf")
+print(result.findings)  # [] when clean
+```
+
+## Streaming
+
+Pass any IO-like object (anything with `read(n) -> bytes`) to `process()` directly — no temp file needed:
+
+```python
+import io
+
+# Scan bytes already in memory
+result = client.process(io.BytesIO(my_bytes), filename="upload.bin")
+
+# Scan content from an open file handle
+with open("./large.pdf", "rb") as f:
+    result = client.process(f, filename="large.pdf")
+```
+
+## API Reference
+
+### Constructor
+
+```python
+ScaniiClient(
+    *,
+    key: str | None = None,
+    secret: str | None = None,
+    token: str | None = None,
+    target: ScaniiTarget,
+    timeout: float = 60.0,
+)
+```
+
+Supply either `key` + `secret` (HTTP Basic Auth) or `token` (auth-token authentication). Mixing both raises `ValueError`. `target` is required — see [Regional Endpoints](#regional-endpoints).
+
+### File scanning
+
+| Method | Description |
+|---|---|
+| `process(content, filename, content_type=None, metadata=None, callback=None)` | Synchronous scan of an IO-like object |
+| `process_file(path, metadata=None, callback=None)` | Synchronous scan of a file on disk |
+| `process_async(content, filename, content_type=None, metadata=None, callback=None)` | Async-on-server scan of an IO-like object; returns `ScaniiPendingResult` |
+| `process_async_file(path, metadata=None, callback=None)` | Async-on-server scan of a file on disk; returns `ScaniiPendingResult` |
+| `retrieve(id)` | Retrieve a previous scan result |
+| `fetch(url, metadata=None, callback=None)` | Server-side async fetch-and-scan of a remote URL |
+
+### v2.2 preview methods
+
+| Method | Description |
+|---|---|
+| `retrieve_trace(id)` **(v2.2 preview)** | Retrieve processing event trace; returns `None` on 404 |
+| `process_from_url(location, callback=None, metadata=None)` **(v2.2 preview)** | Synchronous scan of a remote URL via `POST /files` |
+
+### Auth tokens
+
+| Method | Description |
+|---|---|
+| `create_auth_token(timeout_seconds)` | Mint a short-lived token |
+| `retrieve_auth_token(id)` | Inspect a token |
+| `delete_auth_token(id)` | Revoke a token |
+
+### Health check
+
+| Method | Description |
+|---|---|
+| `ping()` | Returns `True` when the API is reachable with valid credentials |
+
+## Regional Endpoints
+
+Choose a regional target explicitly. Six regional constants are available: `US1`, `EU1`, `EU2`, `AP1`, `AP2`, `CA1`. Latency-based routing (`AUTO` in other Scanii SDKs) is intentionally not provided — chain-of-custody and data-residency compliance require an explicit regional choice. For local testing against scanii-cli, construct a target with an arbitrary URL: `ScaniiTarget("http://localhost:4000")`.
+
+| Constant | URL | Location |
+|---|---|---|
+| `ScaniiTarget.US1` | `https://api-us1.scanii.com` | Virginia, USA |
+| `ScaniiTarget.EU1` | `https://api-eu1.scanii.com` | Dublin, Ireland |
+| `ScaniiTarget.EU2` | `https://api-eu2.scanii.com` | London, United Kingdom |
+| `ScaniiTarget.AP1` | `https://api-ap1.scanii.com` | Sydney, Australia |
+| `ScaniiTarget.AP2` | `https://api-ap2.scanii.com` | Singapore |
+| `ScaniiTarget.CA1` | `https://api-ca1.scanii.com` | Montreal, Canada |
+
+```python
+client = ScaniiClient(key="your-key", secret="your-secret", target=ScaniiTarget.EU1)
+```
+
+## Error Handling
+
+```python
+from scanii import ScaniiClient, ScaniiTarget, ScaniiError, ScaniiAuthError, ScaniiRateLimitError
+import time
+
+client = ScaniiClient(key="your-key", secret="your-secret", target=ScaniiTarget.US1)
+
+try:
+    result = client.process_file("./document.pdf")
+except ScaniiAuthError:
+    print("Invalid credentials")
+except ScaniiRateLimitError as e:
+    if e.retry_after:
+        time.sleep(e.retry_after)
+except ScaniiError as e:
+    print(f"API error {e.status_code}: {e}")
+```
+
+Network-level failures (`urllib.error.URLError`) propagate unwrapped — retries are the caller's responsibility per SDK Principle 3.
+
+## Local Testing with scanii-cli
+
+All integration tests run against a locally-hosted scanii-cli mock server — no real credentials needed.
+
+```bash
+docker run -d --name scanii-cli -p 4000:4000 ghcr.io/scanii/scanii-cli:latest server
+
+# Run tests
+pip install -e ".[dev]"
+pytest
+```
+
+```python
+client = ScaniiClient(key="key", secret="secret", target=ScaniiTarget("http://localhost:4000"))
+result = client.ping()  # True
+```
+
+## Contributing
+
+Pull requests welcome. Please open an issue first for substantial changes.
+
+## License
+
+Apache 2.0 — see [LICENSE](LICENSE).

scanii_python-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+scanii/__init__.py,sha256=UAJKqYO1q8UgR-rGysuj52B6i8m7_O0NVYRQVtpsV84,778
+scanii/_multipart.py,sha256=4V_4Hx3se_0xMP3uIKqZXTK8rasZOtPa2CgCYa8XpEg,6864
+scanii/_version.py,sha256=J-j-u0itpEFT6irdmWmixQqYMadNl1X91TxUmoiLHMI,22
+scanii/client.py,sha256=MoLEIJ5TZ_LgRrm3vAvOL6NaGIIc77rFJz141MbZt4c,18891
+scanii/errors.py,sha256=YYyakKG8fZXMo8CKwOf3gUlF-OFk9NpGDBA4tyfH2bM,1415
+scanii/models.py,sha256=-2U-MfBdyRFdawF0701sHyJAj63KpqeDA_fugC6lzfI,6064
+scanii/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+scanii/target.py,sha256=CjnQdgrwmmp9x_GYGwG2XeSrc5IQ1Aw5BoiqAFZFCXs,2066
+scanii_python-1.0.0.dist-info/METADATA,sha256=kh3tm-CLESlJQkzCSYp2yr0niAIPIRDkkh77by_MR7s,5709
+scanii_python-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+scanii_python-1.0.0.dist-info/licenses/LICENSE,sha256=wPxTrn3rOsJl9dpsbbrr2lLGQbGj5eKShvCgcsto5HQ,10017
+scanii_python-1.0.0.dist-info/RECORD,,

scanii_python-1.0.0.dist-info/WHEEL

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

scanii_python-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,180 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other transformations
+      represent, as a whole, an original work of authorship. For the purposes
+      of this document, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those Contributions necessary to
+      make, have made, use, offer to sell, sell, import, and otherwise
+      transfer the Work, where such license applies only to those
+      Contributions necessary to make, have made, use, offer to sell, sell,
+      import, and otherwise transfer the Work, where such license applies only
+      to those Contributions necessary to make, have made, use, offer to sell,
+      sell, import, and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and where such third-party notices normally
+          appear. The contents of the NOTICE file are for informational
+          purposes only and do not modify the License. You may add Your
+          own attribution notices within Derivative Works that You
+          distribute, alongside or in addition to the NOTICE text from
+          the Work, provided that such additional attribution notices
+          cannot be construed as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, copy, modify, merge,
+      publish, distribute, sublicense, and/or sell copies of the Work,
+      and you may offer support, acceptance, or other conditions.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may offer only
+      on Your behalf, on the sole responsibility of each Contributor, and
+      only if You agree to indemnify, defend, and hold each Contributor
+      harmless for any liability incurred by, or claims asserted against,
+      such Contributor by reason of your accepting any warranty or
+      additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2024 Scanii
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.