boomerang-python 1.0.0__tar.gz

boomerang_python-1.0.0/.gitignore

@@ -0,0 +1,32 @@
+# Maven
+target/
+*.class
+.flattened-pom.xml
+
+# IDE
+.idea/
+*.iml
+.vscode/
+*.swp
+*.swo
+
+
+# Docs (medium posts, drafts, local assets)
+docs/
+
+# Private notes (not for public repo)
+.private/
+
+# macOS
+.DS_Store
+
+# Logs
+*.log
+
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/
+dist/
+.pytest_cache/

boomerang_python-1.0.0/PKG-INFO

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: boomerang-python
+Version: 1.0.0
+Summary: Python SDK for the Boomerang async webhook platform
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.0
+Provides-Extra: dev
+Requires-Dist: fastapi>=0.100; extra == 'dev'
+Requires-Dist: flask>=2.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.100; extra == 'fastapi'
+Provides-Extra: flask
+Requires-Dist: flask>=2.0; extra == 'flask'
+Description-Content-Type: text/markdown
+
+# boomerang-client
+
+Python SDK for the [Boomerang](https://github.com/sameerchereddy/boomerang) async webhook platform.

boomerang_python-1.0.0/README.md

@@ -0,0 +1,3 @@
+# boomerang-client
+
+Python SDK for the [Boomerang](https://github.com/sameerchereddy/boomerang) async webhook platform.

boomerang_python-1.0.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "boomerang-python"
+version = "1.0.0"
+description = "Python SDK for the Boomerang async webhook platform"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+dependencies = [
+    "pydantic>=2.0,<3",
+    "httpx>=0.27,<1",
+]
+
+[project.optional-dependencies]
+fastapi = ["fastapi>=0.100"]
+flask = ["flask>=2.0"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-httpx>=0.30",
+    "fastapi>=0.100",
+    "flask>=2.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/boomerang"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

boomerang_python-1.0.0/src/boomerang/__init__.py

@@ -0,0 +1,29 @@
+from .client import BoomerangClient
+from .errors import (
+    BoomerangConflictError,
+    BoomerangError,
+    BoomerangForbiddenError,
+    BoomerangServiceUnavailableError,
+    BoomerangUnauthorizedError,
+)
+from .models import (
+    BoomerangJobStatus,
+    BoomerangPayload,
+    BoomerangTriggerRequest,
+    BoomerangTriggerResponse,
+)
+from .signature import BoomerangSignature
+
+__all__ = [
+    "BoomerangClient",
+    "BoomerangSignature",
+    "BoomerangError",
+    "BoomerangUnauthorizedError",
+    "BoomerangForbiddenError",
+    "BoomerangConflictError",
+    "BoomerangServiceUnavailableError",
+    "BoomerangTriggerRequest",
+    "BoomerangTriggerResponse",
+    "BoomerangJobStatus",
+    "BoomerangPayload",
+]

boomerang_python-1.0.0/src/boomerang/client.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+from urllib.parse import quote
+
+import httpx
+
+from .errors import (
+    BoomerangConflictError,
+    BoomerangError,
+    BoomerangForbiddenError,
+    BoomerangServiceUnavailableError,
+    BoomerangUnauthorizedError,
+)
+from .models import (
+    BoomerangJobStatus,
+    BoomerangTriggerRequest,
+    BoomerangTriggerResponse,
+)
+
+_STATUS_MAP: dict[int, type[BoomerangError]] = {
+    401: BoomerangUnauthorizedError,
+    403: BoomerangForbiddenError,
+    409: BoomerangConflictError,
+    503: BoomerangServiceUnavailableError,
+}
+
+
+class BoomerangClient:
+    """Thin HTTP client for the Boomerang async webhook service."""
+
+    def __init__(self, base_url: str, token: str) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+        self._client = httpx.Client()
+        self._async_client = httpx.AsyncClient()
+
+    # --- lifecycle ---
+
+    def close(self) -> None:
+        """Close the underlying connection pools."""
+        self._client.close()
+
+    async def aclose(self) -> None:
+        """Close the underlying async connection pool."""
+        await self._async_client.aclose()
+
+    def __enter__(self) -> BoomerangClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    async def __aenter__(self) -> BoomerangClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.aclose()
+
+    # --- headers ---
+
+    def _auth_headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self._token}",
+            "Content-Type": "application/json",
+        }
+
+    # --- error handling ---
+
+    @staticmethod
+    def _raise_for_status(response: httpx.Response) -> None:
+        if response.is_success:
+            return
+        try:
+            body = response.json() if response.content else {}
+        except Exception:
+            body = {}
+        message = body.get("error", response.reason_phrase or "Unknown error")
+        error_cls = _STATUS_MAP.get(response.status_code)
+        if error_cls is BoomerangConflictError:
+            raise BoomerangConflictError(
+                message,
+                retry_after_seconds=body.get("retryAfterSeconds"),
+            )
+        if error_cls is not None:
+            raise error_cls(message)
+        raise BoomerangError(response.status_code, message)
+
+    # --- sync ---
+
+    def trigger(
+        self,
+        worker_url: str,
+        callback_url: str,
+        callback_secret: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> BoomerangTriggerResponse:
+        """Submit a job via ``POST /sync``. Returns the assigned job ID."""
+        req = BoomerangTriggerRequest(
+            worker_url=worker_url,
+            callback_url=callback_url,
+            callback_secret=callback_secret,
+            idempotency_key=idempotency_key,
+        )
+        response = self._client.post(
+            f"{self._base_url}/sync",
+            headers=self._auth_headers(),
+            content=req.model_dump_json(by_alias=True, exclude_none=True),
+        )
+        self._raise_for_status(response)
+        return BoomerangTriggerResponse.model_validate(response.json())
+
+    def poll(self, job_id: str) -> BoomerangJobStatus:
+        """Poll job status via ``GET /sync/{jobId}``."""
+        response = self._client.get(
+            f"{self._base_url}/sync/{quote(job_id, safe='')}",
+            headers=self._auth_headers(),
+        )
+        self._raise_for_status(response)
+        return BoomerangJobStatus.model_validate(response.json())
+
+    # --- async ---
+
+    async def trigger_async(
+        self,
+        worker_url: str,
+        callback_url: str,
+        callback_secret: str | None = None,
+        idempotency_key: str | None = None,
+    ) -> BoomerangTriggerResponse:
+        """Async variant of :meth:`trigger`."""
+        req = BoomerangTriggerRequest(
+            worker_url=worker_url,
+            callback_url=callback_url,
+            callback_secret=callback_secret,
+            idempotency_key=idempotency_key,
+        )
+        response = await self._async_client.post(
+            f"{self._base_url}/sync",
+            headers=self._auth_headers(),
+            content=req.model_dump_json(by_alias=True, exclude_none=True),
+        )
+        self._raise_for_status(response)
+        return BoomerangTriggerResponse.model_validate(response.json())
+
+    async def poll_async(self, job_id: str) -> BoomerangJobStatus:
+        """Async variant of :meth:`poll`."""
+        response = await self._async_client.get(
+            f"{self._base_url}/sync/{quote(job_id, safe='')}",
+            headers=self._auth_headers(),
+        )
+        self._raise_for_status(response)
+        return BoomerangJobStatus.model_validate(response.json())

boomerang_python-1.0.0/src/boomerang/errors.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+
+class BoomerangError(Exception):
+    """Base class for all Boomerang SDK errors."""
+
+    status_code: int = 0
+
+    def __init__(self, status_code: int, message: str) -> None:
+        self.status_code = status_code
+        self.message = message
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        return f"[{self.status_code}] {self.message}"
+
+
+class BoomerangUnauthorizedError(BoomerangError):
+    """401 — missing or invalid JWT."""
+
+    def __init__(self, message: str = "Unauthorized") -> None:
+        super().__init__(401, message)
+
+
+class BoomerangForbiddenError(BoomerangError):
+    """403 — callbackUrl or workerUrl not in the server's allowlist."""
+
+    def __init__(self, message: str = "Forbidden") -> None:
+        super().__init__(403, message)
+
+
+class BoomerangConflictError(BoomerangError):
+    """409 — duplicate job submitted within idempotency cooldown."""
+
+    def __init__(self, message: str = "Conflict", retry_after_seconds: int | None = None) -> None:
+        super().__init__(409, message)
+        self.retry_after_seconds = retry_after_seconds
+
+
+class BoomerangServiceUnavailableError(BoomerangError):
+    """503 — Boomerang worker pool is saturated."""
+
+    def __init__(self, message: str = "Service Unavailable") -> None:
+        super().__init__(503, message)
+
+
+STATUS_CODE_TO_ERROR: dict[int, type[BoomerangError]] = {
+    401: BoomerangUnauthorizedError,
+    403: BoomerangForbiddenError,
+    409: BoomerangConflictError,
+    503: BoomerangServiceUnavailableError,
+}
+
+
+def raise_for_status(status_code: int, message: str) -> None:
+    """Raise the appropriate ``BoomerangError`` subclass for *status_code*."""
+    error_cls = STATUS_CODE_TO_ERROR.get(status_code)
+    if error_cls is not None:
+        raise error_cls(message)
+    raise BoomerangError(status_code, message)

boomerang_python-1.0.0/src/boomerang/middleware/fastapi.py

@@ -0,0 +1,42 @@
+"""FastAPI dependency for verifying Boomerang webhook signatures."""
+
+from typing import Callable
+
+from ..models import BoomerangPayload
+from ..signature import BoomerangSignature
+
+
+def boomerang_webhook(secret: str) -> Callable:
+    """Return a FastAPI dependency callable that verifies the webhook
+    signature and returns a :class:`BoomerangPayload`.
+
+    Usage::
+
+        from fastapi import Depends
+
+        @app.post("/hooks/sync-done")
+        async def on_sync_done(
+            payload: BoomerangPayload = Depends(boomerang_webhook(secret)),
+        ):
+            ...
+    """
+    from fastapi import HTTPException, Request
+
+    async def _verify(request: Request) -> BoomerangPayload:
+        signature = request.headers.get("x-signature-sha256")
+        if not signature:
+            raise HTTPException(status_code=401, detail="Missing X-Signature-SHA256 header")
+
+        body = await request.body()
+
+        try:
+            valid = BoomerangSignature.verify(body, signature, secret)
+        except ValueError:
+            raise HTTPException(status_code=401, detail="Malformed signature header")
+
+        if not valid:
+            raise HTTPException(status_code=401, detail="Invalid signature")
+
+        return BoomerangPayload.model_validate_json(body)
+
+    return _verify

boomerang_python-1.0.0/src/boomerang/middleware/flask.py

@@ -0,0 +1,48 @@
+"""Flask decorator for verifying Boomerang webhook signatures."""
+
+from __future__ import annotations
+
+import functools
+from typing import Any, Callable
+
+from ..models import BoomerangPayload
+from ..signature import BoomerangSignature
+
+
+def boomerang_webhook(secret: str) -> Callable:
+    """Decorator that verifies the webhook signature and injects a
+    :class:`BoomerangPayload` as the first positional argument.
+
+    Usage::
+
+        @app.post("/hooks/sync-done")
+        @boomerang_webhook(secret=os.environ["WEBHOOK_SECRET"])
+        def on_sync_done(payload: BoomerangPayload):
+            ...
+    """
+
+    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            from flask import abort, request  # noqa: lazy import
+
+            signature = request.headers.get("x-signature-sha256")
+            if not signature:
+                abort(401, description="Missing X-Signature-SHA256 header")
+
+            body = request.get_data()
+
+            try:
+                valid = BoomerangSignature.verify(body, signature, secret)
+            except ValueError:
+                abort(401, description="Malformed signature header")
+
+            if not valid:
+                abort(401, description="Invalid signature")
+
+            payload = BoomerangPayload.model_validate_json(body)
+            return fn(payload, *args, **kwargs)
+
+        return wrapper
+
+    return decorator

boomerang_python-1.0.0/src/boomerang/models.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class _CamelModel(BaseModel):
+    """Base model that serialises snake_case fields to camelCase JSON."""
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        frozen=True,
+    )
+
+
+class BoomerangTriggerRequest(_CamelModel):
+    """Request body for ``POST /sync``."""
+
+    worker_url: str = Field(alias="workerUrl")
+    callback_url: str = Field(alias="callbackUrl")
+    callback_secret: str | None = Field(default=None, alias="callbackSecret")
+    idempotency_key: str | None = Field(default=None, alias="idempotencyKey")
+
+
+class BoomerangTriggerResponse(_CamelModel):
+    """Response body returned by ``POST /sync``."""
+
+    job_id: str = Field(alias="jobId")
+
+
+class BoomerangJobStatus(_CamelModel):
+    """Response body returned by ``GET /sync/{jobId}``."""
+
+    job_id: str = Field(alias="jobId")
+    status: Literal["PENDING", "IN_PROGRESS", "DONE", "FAILED"]
+    created_at: str | None = Field(default=None, alias="createdAt")
+    completed_at: str | None = Field(default=None, alias="completedAt")
+    result: dict[str, Any] | None = None
+    error: str | None = None
+
+
+class BoomerangPayload(_CamelModel):
+    """Webhook callback payload delivered to the consumer's ``callbackUrl``.
+
+    This model is immutable (frozen) so middleware can safely pass it around.
+    """
+
+    boomerang_version: str = Field(alias="boomerangVersion")
+    job_id: str = Field(alias="jobId")
+    status: Literal["DONE", "FAILED"]
+    completed_at: datetime = Field(alias="completedAt")
+    result: dict[str, Any] | None = None
+    error: str | None = None

boomerang_python-1.0.0/src/boomerang/signature.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+
+class BoomerangSignature:
+    """HMAC-SHA256 signature verification for Boomerang webhooks."""
+
+    _PREFIX = "sha256="
+
+    @staticmethod
+    def verify(body: bytes, signature_header: str, secret: str) -> bool:
+        """Return ``True`` if *signature_header* is a valid HMAC for *body*.
+
+        Uses constant-time comparison to prevent timing attacks.
+
+        Raises ``ValueError`` if *signature_header* does not start with
+        ``sha256=``.
+        """
+        if not signature_header.startswith(BoomerangSignature._PREFIX):
+            raise ValueError(
+                f"Malformed signature header: expected 'sha256=...' prefix, "
+                f"got {signature_header!r}"
+            )
+        expected = BoomerangSignature.compute(body, secret)
+        return hmac.compare_digest(expected, signature_header)
+
+    @staticmethod
+    def compute(body: bytes, secret: str) -> str:
+        """Return the signature header value: ``sha256=<lowercase hex>``."""
+        digest = hmac.new(
+            secret.encode("utf-8"),
+            body,
+            hashlib.sha256,
+        ).hexdigest()
+        return f"sha256={digest}"

boomerang_python-1.0.0/tests/test_client.py

@@ -0,0 +1,206 @@
+import json
+
+import httpx
+import pytest
+
+from boomerang import (
+    BoomerangConflictError,
+    BoomerangForbiddenError,
+    BoomerangServiceUnavailableError,
+    BoomerangUnauthorizedError,
+)
+from boomerang.client import BoomerangClient
+
+
+BASE = "https://boomerang.test"
+TOKEN = "test-jwt"
+
+
+def _client() -> BoomerangClient:
+    return BoomerangClient(base_url=BASE, token=TOKEN)
+
+
+def _mock_response(status: int, body: dict | None = None) -> httpx.Response:
+    return httpx.Response(
+        status_code=status,
+        json=body or {},
+        request=httpx.Request("GET", BASE),
+    )
+
+
+# ── trigger ──────────────────────────────────────────────────────────
+
+
+class TestTrigger:
+    def test_success(self, httpx_mock):
+        httpx_mock.add_response(
+            url=f"{BASE}/sync",
+            method="POST",
+            status_code=202,
+            json={"jobId": "j1"},
+        )
+        resp = _client().trigger(
+            worker_url="https://w.co/work",
+            callback_url="https://c.co/hook",
+        )
+        assert resp.job_id == "j1"
+
+    def test_sends_auth_header(self, httpx_mock):
+        httpx_mock.add_response(
+            url=f"{BASE}/sync",
+            method="POST",
+            status_code=202,
+            json={"jobId": "j1"},
+        )
+        _client().trigger(
+            worker_url="https://w.co/work",
+            callback_url="https://c.co/hook",
+        )
+        request = httpx_mock.get_request()
+        assert request.headers["authorization"] == f"Bearer {TOKEN}"
+
+    def test_sends_camel_case_body(self, httpx_mock):
+        httpx_mock.add_response(
+            url=f"{BASE}/sync",
+            method="POST",
+            status_code=202,
+            json={"jobId": "j1"},
+        )
+        _client().trigger(
+            worker_url="https://w.co/work",
+            callback_url="https://c.co/hook",
+            callback_secret="s",
+            idempotency_key="k",
+        )
+        body = json.loads(httpx_mock.get_request().content)
+        assert body == {
+            "workerUrl": "https://w.co/work",
+            "callbackUrl": "https://c.co/hook",
+            "callbackSecret": "s",
+            "idempotencyKey": "k",
+        }
+
+    def test_excludes_none_fields(self, httpx_mock):
+        httpx_mock.add_response(
+            url=f"{BASE}/sync",
+            method="POST",
+            status_code=202,
+            json={"jobId": "j1"},
+        )
+        _client().trigger(
+            worker_url="https://w.co/work",
+            callback_url="https://c.co/hook",
+        )
+        body = json.loads(httpx_mock.get_request().content)
+        assert "callbackSecret" not in body
+        assert "idempotencyKey" not in body
+
+
+# ── poll ─────────────────────────────────────────────────────────────
+
+
+class TestPoll:
+    def test_success(self, httpx_mock):
+        httpx_mock.add_response(
+            url=f"{BASE}/sync/j1",
+            method="GET",
+            json={"jobId": "j1", "status": "DONE", "completedAt": "2026-01-01T00:00:00Z"},
+        )
+        status = _client().poll("j1")
+        assert status.job_id == "j1"
+        assert status.status == "DONE"
+
+    def test_url_encodes_job_id(self, httpx_mock):
+        httpx_mock.add_response(
+            url=f"{BASE}/sync/a%2Fb",
+            method="GET",
+            json={"jobId": "a/b", "status": "PENDING"},
+        )
+        status = _client().poll("a/b")
+        assert status.job_id == "a/b"
+
+
+# ── error mapping ───────────────────────────────────────────────────
+
+
+class TestErrorMapping:
+    @pytest.mark.parametrize(
+        "status,error_cls",
+        [
+            (401, BoomerangUnauthorizedError),
+            (403, BoomerangForbiddenError),
+            (409, BoomerangConflictError),
+            (503, BoomerangServiceUnavailableError),
+        ],
+    )
+    def test_known_errors(self, httpx_mock, status, error_cls):
+        httpx_mock.add_response(
+            url=f"{BASE}/sync",
+            method="POST",
+            status_code=status,
+            json={"error": "boom"},
+        )
+        with pytest.raises(error_cls, match="boom"):
+            _client().trigger(
+                worker_url="https://w.co/work",
+                callback_url="https://c.co/hook",
+            )
+
+    def test_conflict_retry_after(self, httpx_mock):
+        httpx_mock.add_response(
+            url=f"{BASE}/sync",
+            method="POST",
+            status_code=409,
+            json={"error": "dup", "retryAfterSeconds": 30},
+        )
+        with pytest.raises(BoomerangConflictError) as exc_info:
+            _client().trigger(
+                worker_url="https://w.co/work",
+                callback_url="https://c.co/hook",
+            )
+        assert exc_info.value.retry_after_seconds == 30
+
+    def test_unknown_error(self, httpx_mock):
+        from boomerang.errors import BoomerangError
+
+        httpx_mock.add_response(
+            url=f"{BASE}/sync",
+            method="POST",
+            status_code=500,
+            json={"error": "internal"},
+        )
+        with pytest.raises(BoomerangError) as exc_info:
+            _client().trigger(
+                worker_url="https://w.co/work",
+                callback_url="https://c.co/hook",
+            )
+        assert exc_info.value.status_code == 500
+
+
+# ── async ────────────────────────────────────────────────────────────
+
+
+class TestAsync:
+    @pytest.mark.asyncio
+    async def test_trigger_async(self, httpx_mock):
+        httpx_mock.add_response(
+            url=f"{BASE}/sync",
+            method="POST",
+            status_code=202,
+            json={"jobId": "j1"},
+        )
+        resp = await _client().trigger_async(
+            worker_url="https://w.co/work",
+            callback_url="https://c.co/hook",
+        )
+        assert resp.job_id == "j1"
+
+    @pytest.mark.asyncio
+    async def test_poll_async(self, httpx_mock):
+        httpx_mock.add_response(
+            url=f"{BASE}/sync/j1",
+            method="GET",
+            json={"jobId": "j1", "status": "PENDING"},
+        )
+        status = await _client().poll_async("j1")
+        assert status.status == "PENDING"

boomerang_python-1.0.0/tests/test_errors.py

@@ -0,0 +1,75 @@
+import pytest
+
+from boomerang.errors import (
+    BoomerangConflictError,
+    BoomerangError,
+    BoomerangForbiddenError,
+    BoomerangServiceUnavailableError,
+    BoomerangUnauthorizedError,
+    raise_for_status,
+)
+
+
+class TestBoomerangError:
+    def test_base_error(self):
+        err = BoomerangError(500, "Internal Server Error")
+        assert err.status_code == 500
+        assert err.message == "Internal Server Error"
+        assert str(err) == "[500] Internal Server Error"
+
+    def test_is_exception(self):
+        assert issubclass(BoomerangError, Exception)
+
+    def test_catchable_by_base(self):
+        with pytest.raises(BoomerangError):
+            raise BoomerangUnauthorizedError("bad token")
+
+
+class TestSubclasses:
+    def test_unauthorized(self):
+        err = BoomerangUnauthorizedError("Invalid JWT")
+        assert err.status_code == 401
+        assert str(err) == "[401] Invalid JWT"
+
+    def test_unauthorized_default(self):
+        err = BoomerangUnauthorizedError()
+        assert str(err) == "[401] Unauthorized"
+
+    def test_forbidden(self):
+        err = BoomerangForbiddenError("URL not allowed")
+        assert err.status_code == 403
+
+    def test_conflict(self):
+        err = BoomerangConflictError("Duplicate key", retry_after_seconds=30)
+        assert err.status_code == 409
+        assert err.retry_after_seconds == 30
+
+    def test_conflict_no_retry(self):
+        err = BoomerangConflictError()
+        assert err.retry_after_seconds is None
+
+    def test_service_unavailable(self):
+        err = BoomerangServiceUnavailableError("Pool full")
+        assert err.status_code == 503
+
+
+class TestRaiseForStatus:
+    @pytest.mark.parametrize(
+        "code,expected_cls",
+        [
+            (401, BoomerangUnauthorizedError),
+            (403, BoomerangForbiddenError),
+            (409, BoomerangConflictError),
+            (503, BoomerangServiceUnavailableError),
+        ],
+    )
+    def test_known_codes(self, code, expected_cls):
+        with pytest.raises(expected_cls) as exc_info:
+            raise_for_status(code, "msg")
+        assert exc_info.value.status_code == code
+
+    def test_unknown_code_raises_base(self):
+        with pytest.raises(BoomerangError) as exc_info:
+            raise_for_status(502, "Bad Gateway")
+        assert exc_info.value.status_code == 502
+        assert not isinstance(exc_info.value, BoomerangUnauthorizedError)

boomerang_python-1.0.0/tests/test_middleware_fastapi.py

@@ -0,0 +1,68 @@
+import json
+
+import pytest
+
+from boomerang.signature import BoomerangSignature
+
+SECRET = "test-secret"
+PAYLOAD = {
+    "boomerangVersion": "1",
+    "jobId": "j1",
+    "status": "DONE",
+    "completedAt": "2026-03-22T10:00:18Z",
+    "result": {"key": "value"},
+}
+BODY = json.dumps(PAYLOAD).encode()
+VALID_SIG = BoomerangSignature.compute(BODY, SECRET)
+
+
+@pytest.fixture()
+def fastapi_client():
+    from fastapi import Depends, FastAPI
+    from fastapi.testclient import TestClient
+
+    from boomerang.middleware.fastapi import boomerang_webhook
+    from boomerang.models import BoomerangPayload
+
+    app = FastAPI()
+
+    @app.post("/hooks")
+    async def hook(payload: BoomerangPayload = Depends(boomerang_webhook(SECRET))):
+        return {"job_id": payload.job_id, "status": payload.status}
+
+    return TestClient(app)
+
+
+class TestFastAPIMiddleware:
+    def test_valid_signature(self, fastapi_client):
+        resp = fastapi_client.post(
+            "/hooks",
+            content=BODY,
+            headers={"X-Signature-SHA256": VALID_SIG, "Content-Type": "application/json"},
+        )
+        assert resp.status_code == 200
+        assert resp.json()["job_id"] == "j1"
+
+    def test_missing_signature_returns_401(self, fastapi_client):
+        resp = fastapi_client.post(
+            "/hooks",
+            content=BODY,
+            headers={"Content-Type": "application/json"},
+        )
+        assert resp.status_code == 401
+
+    def test_invalid_signature_returns_401(self, fastapi_client):
+        resp = fastapi_client.post(
+            "/hooks",
+            content=BODY,
+            headers={"X-Signature-SHA256": "sha256=" + "a" * 64, "Content-Type": "application/json"},
+        )
+        assert resp.status_code == 401
+
+    def test_malformed_signature_returns_401(self, fastapi_client):
+        resp = fastapi_client.post(
+            "/hooks",
+            content=BODY,
+            headers={"X-Signature-SHA256": "bad", "Content-Type": "application/json"},
+        )
+        assert resp.status_code == 401

boomerang_python-1.0.0/tests/test_middleware_flask.py

@@ -0,0 +1,69 @@
+import json
+
+import pytest
+
+from boomerang.signature import BoomerangSignature
+
+SECRET = "test-secret"
+PAYLOAD = {
+    "boomerangVersion": "1",
+    "jobId": "j1",
+    "status": "DONE",
+    "completedAt": "2026-03-22T10:00:18Z",
+    "result": {"key": "value"},
+}
+BODY = json.dumps(PAYLOAD).encode()
+VALID_SIG = BoomerangSignature.compute(BODY, SECRET)
+
+
+@pytest.fixture()
+def flask_client():
+    from flask import Flask, jsonify
+
+    from boomerang.middleware.flask import boomerang_webhook
+    from boomerang.models import BoomerangPayload
+
+    app = Flask(__name__)
+
+    @app.post("/hooks")
+    @boomerang_webhook(secret=SECRET)
+    def hook(payload: BoomerangPayload):
+        return jsonify(job_id=payload.job_id, status=payload.status)
+
+    app.config["TESTING"] = True
+    return app.test_client()
+
+
+class TestFlaskMiddleware:
+    def test_valid_signature(self, flask_client):
+        resp = flask_client.post(
+            "/hooks",
+            data=BODY,
+            headers={"X-Signature-SHA256": VALID_SIG, "Content-Type": "application/json"},
+        )
+        assert resp.status_code == 200
+        assert resp.get_json()["job_id"] == "j1"
+
+    def test_missing_signature_returns_401(self, flask_client):
+        resp = flask_client.post(
+            "/hooks",
+            data=BODY,
+            headers={"Content-Type": "application/json"},
+        )
+        assert resp.status_code == 401
+
+    def test_invalid_signature_returns_401(self, flask_client):
+        resp = flask_client.post(
+            "/hooks",
+            data=BODY,
+            headers={"X-Signature-SHA256": "sha256=" + "a" * 64, "Content-Type": "application/json"},
+        )
+        assert resp.status_code == 401
+
+    def test_malformed_signature_returns_401(self, flask_client):
+        resp = flask_client.post(
+            "/hooks",
+            data=BODY,
+            headers={"X-Signature-SHA256": "bad", "Content-Type": "application/json"},
+        )
+        assert resp.status_code == 401

boomerang_python-1.0.0/tests/test_models.py

@@ -0,0 +1,161 @@
+from datetime import datetime, timezone
+
+import pytest
+from pydantic import ValidationError
+
+from boomerang import (
+    BoomerangJobStatus,
+    BoomerangPayload,
+    BoomerangTriggerRequest,
+    BoomerangTriggerResponse,
+)
+
+
+class TestBoomerangTriggerRequest:
+    def test_required_fields(self):
+        req = BoomerangTriggerRequest(
+            worker_url="https://example.com/worker",
+            callback_url="https://example.com/callback",
+        )
+        assert req.worker_url == "https://example.com/worker"
+        assert req.callback_url == "https://example.com/callback"
+        assert req.callback_secret is None
+        assert req.idempotency_key is None
+
+    def test_all_fields(self):
+        req = BoomerangTriggerRequest(
+            worker_url="https://example.com/worker",
+            callback_url="https://example.com/callback",
+            callback_secret="secret",
+            idempotency_key="key-123",
+        )
+        assert req.callback_secret == "secret"
+        assert req.idempotency_key == "key-123"
+
+    def test_serialise_to_camel_case(self):
+        req = BoomerangTriggerRequest(
+            worker_url="https://example.com/worker",
+            callback_url="https://example.com/callback",
+            callback_secret="s",
+        )
+        data = req.model_dump(by_alias=True, exclude_none=True)
+        assert data == {
+            "workerUrl": "https://example.com/worker",
+            "callbackUrl": "https://example.com/callback",
+            "callbackSecret": "s",
+        }
+
+    def test_deserialise_from_camel_case(self):
+        req = BoomerangTriggerRequest.model_validate(
+            {"workerUrl": "https://w.co", "callbackUrl": "https://c.co"}
+        )
+        assert req.worker_url == "https://w.co"
+
+    def test_immutable(self):
+        req = BoomerangTriggerRequest(
+            worker_url="https://example.com/worker",
+            callback_url="https://example.com/callback",
+        )
+        with pytest.raises(ValidationError):
+            req.worker_url = "https://other.com"
+
+
+class TestBoomerangTriggerResponse:
+    def test_from_json(self):
+        resp = BoomerangTriggerResponse.model_validate({"jobId": "abc-123"})
+        assert resp.job_id == "abc-123"
+
+    def test_serialise(self):
+        resp = BoomerangTriggerResponse(job_id="abc-123")
+        assert resp.model_dump(by_alias=True) == {"jobId": "abc-123"}
+
+
+class TestBoomerangJobStatus:
+    def test_pending(self):
+        status = BoomerangJobStatus.model_validate(
+            {"jobId": "j1", "status": "PENDING"}
+        )
+        assert status.status == "PENDING"
+        assert status.completed_at is None
+        assert status.result is None
+
+    def test_done(self):
+        status = BoomerangJobStatus.model_validate(
+            {
+                "jobId": "j1",
+                "status": "DONE",
+                "completedAt": "2026-03-22T10:00:18Z",
+                "result": {"key": "value"},
+            }
+        )
+        assert status.status == "DONE"
+        assert status.result == {"key": "value"}
+
+    def test_failed(self):
+        status = BoomerangJobStatus.model_validate(
+            {"jobId": "j1", "status": "FAILED", "error": "boom"}
+        )
+        assert status.status == "FAILED"
+        assert status.error == "boom"
+
+    def test_invalid_status_rejected(self):
+        with pytest.raises(ValidationError):
+            BoomerangJobStatus.model_validate(
+                {"jobId": "j1", "status": "UNKNOWN"}
+            )
+
+
+class TestBoomerangPayload:
+    def test_done_payload(self):
+        payload = BoomerangPayload.model_validate(
+            {
+                "boomerangVersion": "1",
+                "jobId": "j1",
+                "status": "DONE",
+                "completedAt": "2026-03-22T10:00:18Z",
+                "result": {"report": "url"},
+            }
+        )
+        assert payload.boomerang_version == "1"
+        assert payload.job_id == "j1"
+        assert payload.status == "DONE"
+        assert isinstance(payload.completed_at, datetime)
+        assert payload.result == {"report": "url"}
+        assert payload.error is None
+
+    def test_failed_payload(self):
+        payload = BoomerangPayload.model_validate(
+            {
+                "boomerangVersion": "1",
+                "jobId": "j1",
+                "status": "FAILED",
+                "completedAt": "2026-03-22T10:00:18Z",
+                "error": "timeout",
+            }
+        )
+        assert payload.error == "timeout"
+        assert payload.result is None
+
+    def test_immutable(self):
+        payload = BoomerangPayload.model_validate(
+            {
+                "boomerangVersion": "1",
+                "jobId": "j1",
+                "status": "DONE",
+                "completedAt": "2026-03-22T10:00:18Z",
+            }
+        )
+        with pytest.raises(ValidationError):
+            payload.job_id = "other"
+
+    def test_serialise_to_camel_case(self):
+        payload = BoomerangPayload(
+            boomerang_version="1",
+            job_id="j1",
+            status="DONE",
+            completed_at=datetime(2026, 3, 22, 10, 0, 18, tzinfo=timezone.utc),
+        )
+        data = payload.model_dump(by_alias=True, exclude_none=True)
+        assert "boomerangVersion" in data
+        assert "jobId" in data
+        assert "completedAt" in data

boomerang_python-1.0.0/tests/test_signature.py

@@ -0,0 +1,66 @@
+import hashlib
+import hmac
+
+import pytest
+
+from boomerang.signature import BoomerangSignature
+
+
+SECRET = "test-secret"
+BODY = b'{"jobId":"abc-123","status":"DONE"}'
+
+
+def _expected_sig(body: bytes = BODY, secret: str = SECRET) -> str:
+    digest = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
+    return f"sha256={digest}"
+
+
+class TestCompute:
+    def test_returns_sha256_prefix(self):
+        result = BoomerangSignature.compute(BODY, SECRET)
+        assert result.startswith("sha256=")
+
+    def test_lowercase_hex(self):
+        result = BoomerangSignature.compute(BODY, SECRET)
+        hex_part = result.removeprefix("sha256=")
+        assert hex_part == hex_part.lower()
+        assert len(hex_part) == 64  # SHA-256 = 64 hex chars
+
+    def test_matches_stdlib_hmac(self):
+        assert BoomerangSignature.compute(BODY, SECRET) == _expected_sig()
+
+    def test_different_secret_different_sig(self):
+        sig1 = BoomerangSignature.compute(BODY, "secret-a")
+        sig2 = BoomerangSignature.compute(BODY, "secret-b")
+        assert sig1 != sig2
+
+    def test_different_body_different_sig(self):
+        sig1 = BoomerangSignature.compute(b"body-a", SECRET)
+        sig2 = BoomerangSignature.compute(b"body-b", SECRET)
+        assert sig1 != sig2
+
+
+class TestVerify:
+    def test_valid_signature(self):
+        sig = _expected_sig()
+        assert BoomerangSignature.verify(BODY, sig, SECRET) is True
+
+    def test_invalid_signature(self):
+        bad_sig = "sha256=" + "a" * 64
+        assert BoomerangSignature.verify(BODY, bad_sig, SECRET) is False
+
+    def test_wrong_secret(self):
+        sig = _expected_sig(secret="wrong")
+        assert BoomerangSignature.verify(BODY, sig, SECRET) is False
+
+    def test_malformed_header_raises(self):
+        with pytest.raises(ValueError, match="Malformed signature header"):
+            BoomerangSignature.verify(BODY, "bad-header", SECRET)
+
+    def test_empty_prefix_raises(self):
+        with pytest.raises(ValueError):
+            BoomerangSignature.verify(BODY, "abcdef1234", SECRET)
+
+    def test_empty_body(self):
+        sig = BoomerangSignature.compute(b"", SECRET)
+        assert BoomerangSignature.verify(b"", sig, SECRET) is True