waysdrop 1.0.0__tar.gz

waysdrop-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+    push:
+        branches: [main, master]
+        tags: ["v*"]
+    pull_request:
+
+jobs:
+    test:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-python@v5
+              with:
+                  python-version: "3.11"
+            - run: pip install httpx
+            - run: python tests/run_tests.py
+
+    publish:
+        if: startsWith(github.ref, 'refs/tags/v')
+        needs: test
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+            - uses: actions/setup-python@v5
+              with:
+                  python-version: "3.11"
+            - run: pip install build twine
+            - run: python -m build
+            - run: twine upload dist/*
+              env:
+                  TWINE_USERNAME: __token__
+                  TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}

waysdrop-1.0.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.DS_Store
+.env
+.env.*

waysdrop-1.0.0/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 1.0.0
+
+- Initial release: Partner API client (18 endpoints) + webhook verify/parse
+- Typed response models and webhook event discriminated unions

waysdrop-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Waysdrop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

waysdrop-1.0.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.5
+Name: waysdrop
+Version: 1.0.0
+Summary: Official Waysdrop Partner API SDK for Python
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,delivery,sdk,waysdrop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# waysdrop
+
+Official Waysdrop Partner API SDK for Python.
+
+## Install
+
+```bash
+pip install waysdrop
+```
+
+## Quickstart
+
+```python
+from waysdrop import WaysdropClient
+
+client = WaysdropClient(api_key="wsp_staging_...", display_currency="NGN")
+account = client.get_account()
+client.close()
+```
+
+## Webhooks
+
+```python
+from waysdrop import verify_signature, parse_webhook
+
+if not verify_signature(request.body, request.headers.get("x-waysdrop-signature"), API_KEY):
+    return Response(status=401)
+event = parse_webhook(request.body)
+```
+
+## License
+
+MIT

waysdrop-1.0.0/README.md

@@ -0,0 +1,33 @@
+# waysdrop
+
+Official Waysdrop Partner API SDK for Python.
+
+## Install
+
+```bash
+pip install waysdrop
+```
+
+## Quickstart
+
+```python
+from waysdrop import WaysdropClient
+
+client = WaysdropClient(api_key="wsp_staging_...", display_currency="NGN")
+account = client.get_account()
+client.close()
+```
+
+## Webhooks
+
+```python
+from waysdrop import verify_signature, parse_webhook
+
+if not verify_signature(request.body, request.headers.get("x-waysdrop-signature"), API_KEY):
+    return Response(status=401)
+event = parse_webhook(request.body)
+```
+
+## License
+
+MIT

waysdrop-1.0.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "waysdrop"
+version = "1.0.0"
+description = "Official Waysdrop Partner API SDK for Python"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = [
+  "httpx>=0.27.0",
+]
+keywords = ["waysdrop", "delivery", "api", "sdk"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/waysdrop"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

waysdrop-1.0.0/src/waysdrop/__init__.py

@@ -0,0 +1,59 @@
+"""Waysdrop Partner API SDK for Python."""
+
+from waysdrop.types import (
+    FleetType,
+    CityLocation,
+    StateLocation,
+    AccountSummary,
+    DeliveryDetail,
+    MerchantWallet,
+    CountryLocation,
+    DeliveryPackage,
+    DeliverySummary,
+    PricingResponse,
+    WebhookEnvelope,
+    WebhookEventName,
+    RouteDataResponse,
+    ExchangeRateResponse,
+    ListDeliveriesResponse,
+    CancelDeliveryResponse,
+    CreateDeliveryResponse,
+    ConvertCurrencyResponse,
+    PaymentCheckoutResponse,
+)
+from waysdrop.client import AsyncWaysdropClient, WaysdropClient
+from waysdrop.errors import WaysdropError, infer_base_url, validate_api_key
+from waysdrop.webhooks import is_webhook_event, parse_webhook, parse_webhook_event, verify_signature
+
+__all__ = [
+    "WaysdropClient",
+    "AsyncWaysdropClient",
+    "WaysdropError",
+    "infer_base_url",
+    "validate_api_key",
+    "verify_signature",
+    "parse_webhook",
+    "parse_webhook_event",
+    "is_webhook_event",
+    "AccountSummary",
+    "CancelDeliveryResponse",
+    "CityLocation",
+    "ConvertCurrencyResponse",
+    "CountryLocation",
+    "CreateDeliveryResponse",
+    "DeliveryDetail",
+    "DeliveryPackage",
+    "DeliverySummary",
+    "ExchangeRateResponse",
+    "FleetType",
+    "ListDeliveriesResponse",
+    "MerchantWallet",
+    "PaymentCheckoutResponse",
+    "PricingResponse",
+    "RouteDataResponse",
+    "StateLocation",
+    "WebhookEnvelope",
+    "WebhookEventName",
+]
+
+__version__ = "1.0.0"

waysdrop-1.0.0/src/waysdrop/client.py

@@ -0,0 +1,249 @@
+from __future__ import annotations
+
+from typing import Mapping, cast
+
+import httpx
+
+from waysdrop.types import (
+    FleetType,
+    CityLocation,
+    StateLocation,
+    AccountSummary,
+    DeliveryDetail,
+    MerchantWallet,
+    CountryLocation,
+    DeliveryPackage,
+    PricingResponse,
+    WebhookEnvelope,
+    RouteDataResponse,
+    ExchangeRateResponse,
+    CancelDeliveryResponse,
+    CreateDeliveryResponse,
+    ListDeliveriesResponse,
+    ConvertCurrencyResponse,
+    PaymentCheckoutResponse,
+)
+from waysdrop.errors import WaysdropError, infer_base_url, validate_api_key
+
+
+class WaysdropClient:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        display_currency: str | None = None,
+        correlation_id: str | None = None,
+        client: httpx.Client | None = None,
+    ) -> None:
+        validate_api_key(api_key)
+        self._api_key = api_key
+        self._base_url = (base_url or infer_base_url(api_key)).rstrip("/")
+        self._timeout = timeout
+        self._display_currency = display_currency
+        self._correlation_id = correlation_id
+        self._client = client or httpx.Client(timeout=timeout)
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> WaysdropClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    def list_countries(self, *, search: str | None = None, limit: int | None = None) -> list[CountryLocation]:
+        return cast(list[CountryLocation], self._get("/api/countries", search=search, limit=limit))
+
+    def list_states(self, *, search: str | None = None, limit: int | None = None) -> list[StateLocation]:
+        return cast(list[StateLocation], self._get("/api/states", search=search, limit=limit))
+
+    def list_cities(self, *, search: str | None = None, limit: int | None = None) -> list[CityLocation]:
+        return cast(list[CityLocation], self._get("/api/cities", search=search, limit=limit))
+
+    def get_route(self, origin: dict, destination: dict) -> RouteDataResponse:
+        return cast(RouteDataResponse, self._post("/api/route", {"origin": origin, "destination": destination}))
+
+    def list_fleet_types(self) -> list[FleetType]:
+        return cast(list[FleetType], self._get("/api/fleet-types"))
+
+    def get_pricing(self, body: dict, *, currency: str | None = None) -> PricingResponse:
+    def create_or_update_package(self, body: dict, *, currency: str | None = None) -> DeliveryPackage:
+        return cast(PricingResponse, self._post("/api/pricing", self._with_currency(body, currency), currency=currency))
+
+    def create_delivery_request(self, body: dict, *, currency: str | None = None) -> CreateDeliveryResponse:
+
+        self._request("DELETE", f"/api/package/{package_id}")
+        return cast(CreateDeliveryResponse, self._post("/api/request", self._with_currency(body, currency), currency=currency))
+    def cancel_delivery_request(self, delivery_id: str) -> CancelDeliveryResponse:
+        return cast(CancelDeliveryResponse, self._post(f"/api/request/{delivery_id}/cancel", {}))
+
+
+        return cast(DeliveryPackage, self._post("/api/package", self._with_currency(body, currency), currency=currency))
+
+    def delete_package(self, package_id: str) -> None:
+    def list_packages(self, *, currency: str | None = None) -> list[DeliveryPackage]:
+        return cast(list[DeliveryPackage], self._get("/api/packages", currency=currency))
+
+    def get_wallet(self, *, currency: str | None = None) -> MerchantWallet:
+        return cast(MerchantWallet, self._get("/api/wallet", currency=currency))
+
+    def create_payment_checkout(self, body: dict, *, currency: str | None = None) -> PaymentCheckoutResponse:
+        return cast(PaymentCheckoutResponse, self._post("/api/payments/checkout", self._with_currency(body, currency), currency=currency))
+
+    def get_account(self) -> AccountSummary:
+        return cast(AccountSummary, self._get("/api/account"))
+
+    def get_exchange_rate(self, from_currency: str, to_currency: str) -> ExchangeRateResponse:
+        return cast(ExchangeRateResponse, self._get("/api/exchange-rate", from_=from_currency, to=to_currency))
+
+    def convert_currency(self, amount: float, from_currency: str, to_currency: str) -> ConvertCurrencyResponse:
+        return cast(ConvertCurrencyResponse, self._get("/api/convert", amount=amount, from_=from_currency, to=to_currency))
+
+    def list_deliveries(
+        self,
+        *,
+        status: str | None = None,
+        search: str | None = None,
+        page: int | None = None,
+        limit: int | None = None,
+        currency: str | None = None,
+    ) -> ListDeliveriesResponse:
+        return cast(
+            ListDeliveriesResponse,
+            self._get("/api/deliveries", status=status, search=search, page=page, limit=limit, currency=currency),
+        )
+
+    def get_delivery(self, delivery_id: str, *, currency: str | None = None) -> DeliveryDetail:
+        return cast(DeliveryDetail, self._get(f"/api/deliveries/{delivery_id}", currency=currency))
+
+    def _with_currency(self, body: dict, currency: str | None) -> dict:
+        c = currency or self._display_currency
+        if c and "currency" not in body:
+            return {**body, "currency": c}
+        return body
+
+    def _get(self, path: str, **params: object) -> object:
+        return self._request("GET", path, params={k: v for k, v in params.items() if v is not None})
+
+    def _post(self, path: str, body: dict, *, currency: str | None = None) -> object:
+        params: dict[str, str] = {}
+        c = currency or self._display_currency
+        if c:
+            params["currency"] = c
+        return self._request("POST", path, json=body, params=params or None)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, object] | None = None,
+        json: dict | None = None,
+    ) -> object:
+        headers = {"api-key": self._api_key, "Accept": "application/json"}
+        if self._correlation_id:
+            headers["X-Correlation-Id"] = self._correlation_id
+
+        query = dict(params or {})
+        if method == "GET" and self._display_currency and "currency" not in query:
+            query.setdefault("currency", self._display_currency)
+
+        response = self._client.request(
+            method,
+            f"{self._base_url}{path}",
+            headers=headers,
+            params=query or None,
+            json=json,
+        )
+
+        if response.status_code == 204:
+            return None
+
+        data = response.json() if response.content else {}
+
+        if not response.is_success:
+            message = data.get("message", response.reason_phrase)
+            if not isinstance(message, str):
+                message = str(message)
+            raise WaysdropError(
+                message,
+                status_code=data.get("statusCode", response.status_code),
+                details=data.get("details"),
+                quota=data.get("quota"),
+                path=data.get("path"),
+            )
+
+        if isinstance(data, dict) and data.get("success") is True and "data" in data:
+            return data["data"]
+        return data
+
+
+class AsyncWaysdropClient:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+        display_currency: str | None = None,
+        correlation_id: str | None = None,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        validate_api_key(api_key)
+        self._api_key = api_key
+        self._base_url = (base_url or infer_base_url(api_key)).rstrip("/")
+        self._timeout = timeout
+        self._display_currency = display_currency
+        self._correlation_id = correlation_id
+        self._client = client or httpx.AsyncClient(timeout=timeout)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def get_account(self) -> AccountSummary:
+        return cast(AccountSummary, await self._arequest("GET", "/api/account"))
+
+    async def list_fleet_types(self) -> list[FleetType]:
+        return cast(list[FleetType], await self._arequest("GET", "/api/fleet-types"))
+
+    async def _arequest(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, object] | None = None,
+        json: dict | None = None,
+    ) -> object:
+        headers = {"api-key": self._api_key, "Accept": "application/json"}
+        if self._correlation_id:
+            headers["X-Correlation-Id"] = self._correlation_id
+
+        response = await self._client.request(
+            method,
+            f"{self._base_url}{path}",
+            headers=headers,
+            params=params,
+            json=json,
+        )
+
+        if response.status_code == 204:
+            return None
+
+        data = response.json() if response.content else {}
+        if not response.is_success:
+            message = data.get("message", response.reason_phrase)
+            if not isinstance(message, str):
+                message = str(message)
+            raise WaysdropError(
+                message,
+                status_code=data.get("statusCode", response.status_code),
+                details=data.get("details"),
+                quota=data.get("quota"),
+            )
+
+        if isinstance(data, dict) and data.get("success") is True and "data" in data:
+            return data["data"]
+        return data

waysdrop-1.0.0/src/waysdrop/errors.py

@@ -0,0 +1,36 @@
+import re
+from typing import Any, Optional
+
+API_KEY_PATTERN = re.compile(r"^wsp_(live|staging)_[a-f0-9]{64}$")
+
+
+class WaysdropError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        details: Optional[dict[str, Any]] = None,
+        quota: Optional[dict[str, Any]] = None,
+        path: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.details = details
+        self.quota = quota
+        self.path = path
+
+
+def validate_api_key(api_key: str) -> None:
+    if not API_KEY_PATTERN.match(api_key):
+        raise ValueError(
+            "Invalid API key format. Expected wsp_live_… or wsp_staging_… with 64 hex chars."
+        )
+
+
+def infer_base_url(api_key: str) -> str:
+    if api_key.startswith("wsp_staging_"):
+        return "https://staging-api.waysdrop.com"
+    if api_key.startswith("wsp_live_"):
+        return "https://api.waysdrop.com"
+    return "https://staging-api.waysdrop.com"

waysdrop-1.0.0/src/waysdrop/types.py

@@ -0,0 +1,244 @@
+from __future__ import annotations
+
+from typing import Literal, NotRequired, TypedDict
+
+DeliveryStatus = Literal[
+    "REQUEST_CREATED",
+    "ASSIGNING",
+    "ACCEPTED",
+    "AWAITING_COLLECTION",
+    "PACKAGE_COLLECTED",
+    "IN_TRANSIT",
+    "DELIVERED",
+    "CANCELLED",
+]
+
+RouteType = Literal["INTRA_CITY", "INTER_CITY", "INTER_STATE", "INTER_COUNTRY"]
+PackageSize = Literal["SMALL", "MEDIUM", "LARGE", "EXTRA_LARGE"]
+PaymentProcessor = Literal["PAYSTACK", "NOMBA", "STRIPE"]
+DeliveryType = Literal["P2P", "ERRAND", "STORE", "PERSONAL"]
+
+WebhookEventName = Literal[
+    "p2p.delivery.created",
+    "p2p.delivery.cancelled",
+    "errand.delivery.created",
+    "errand.delivery.cancelled",
+    "delivery.request.accepted",
+    "delivery.request.declined",
+    "delivery.awaiting.collection",
+    "delivery.collected",
+    "delivery.in.transit",
+    "delivery.delivered",
+    "delivery.reassignment.created",
+    "delivery.reassignment.direct_assigned",
+    "delivery.reassignment.requested",
+    "delivery.reassignment.collected",
+    "payment.received",
+    "order.created",
+    "order.cancelled",
+    "order.confirmed",
+    "order.declined",
+    "order.requested",
+]
+
+
+class DisplayMoneyLocal(TypedDict, total=False):
+    currency: str
+    amount: float
+    symbol: str
+
+
+class DisplayMoney(TypedDict):
+    usd: float
+    local: NotRequired[DisplayMoneyLocal]
+
+
+class DistanceInfo(TypedDict):
+    distanceKm: float
+    etaSeconds: float
+
+
+class GeoLocation(TypedDict, total=False):
+    id: str
+    addressLine1: str
+    lgaOrCity: str
+    state: str
+    country: str
+    countryCode: str
+    lat: float
+    lon: float
+    googlePlaceId: str
+
+
+class CountryLocation(TypedDict, total=False):
+    value: str
+    name: str
+    type: Literal["INTER_COUNTRY"]
+    country: str
+    countryCode: str
+
+
+class StateLocation(TypedDict, total=False):
+    value: str
+    name: str
+    type: Literal["INTER_STATE"]
+    state: str
+    country: str
+    countryCode: str
+
+
+class CityLocation(TypedDict, total=False):
+    locationId: str
+    value: str
+    country: str
+    countryCode: str
+    lat: float
+    lon: float
+    lgaOrCity: str
+    state: str
+
+
+class FleetType(TypedDict, total=False):
+    id: str
+    name: str
+    icon: str | None
+    description: str | None
+
+
+class PricingCosts(TypedDict, total=False):
+    base: float | str
+    weight: float | str
+    fleet: float | str
+    insurance: float | str
+    surcharge: float | str
+    serviceFee: float | str
+    deliverySubtotal: float | str
+    total: float | str
+    totalDisplay: DisplayMoney
+
+
+class PricingResponse(TypedDict, total=False):
+    distance: DistanceInfo
+    routeType: RouteType
+    costs: PricingCosts
+
+
+class RouteDataResponse(TypedDict):
+    distance: DistanceInfo
+    routeType: RouteType
+    origin: GeoLocation
+    destination: GeoLocation
+
+
+class DeliveryPackage(TypedDict, total=False):
+    id: str
+    name: str
+    quantity: int
+    weight: float | str
+    value: float | str
+    valueDisplay: DisplayMoney
+    size: PackageSize
+    p2pDeliveryId: str | None
+
+
+class DeliverySummary(TypedDict, total=False):
+    id: str
+    trackingId: str
+    status: DeliveryStatus
+    type: DeliveryType
+    routeType: RouteType
+    deliveryFee: float | str
+    deliveryFeeDisplay: DisplayMoney
+    origin: GeoLocation
+    destination: GeoLocation
+
+
+class DeliveryDetail(DeliverySummary, total=False):
+    deliverySteps: list[dict[str, object]]
+    proofs: list[dict[str, object]]
+    fleetType: FleetType
+    p2pDelivery: dict[str, object]
+    courier: dict[str, object]
+
+
+class CreateDeliveryResponse(TypedDict, total=False):
+    id: str
+    status: str
+    totalWeight: float | str
+    totalValue: float | str
+    deliveryId: str
+    delivery: DeliverySummary
+    processor: PaymentProcessor
+    reference: str
+    charge_currency: str
+    charge_amount: float
+    authorization_url: str
+    checkout_url: str
+
+
+class CancelDeliveryResponse(TypedDict):
+    delivery: dict[str, str]
+
+
+class MerchantWallet(TypedDict, total=False):
+    id: str
+    currencyCode: str
+    balance: str
+    balanceDisplay: DisplayMoney
+
+
+class PaymentCheckoutResponse(TypedDict, total=False):
+    processor: PaymentProcessor
+    reference: str
+    charge_currency: str
+    charge_amount: float
+    authorization_url: str
+    checkout_url: str
+
+
+class StoreProfile(TypedDict):
+    id: str
+    name: str
+    tag: str
+
+
+class AccountSummary(TypedDict, total=False):
+    userId: str
+    countryCode: str
+    displayCurrency: str
+    merchantWalletCurrencyCode: str
+    storeProfile: StoreProfile | None
+
+
+ExchangeRateResponse = TypedDict(
+    "ExchangeRateResponse",
+    {"from": str, "to": str, "rate": float, "isStale": NotRequired[bool]},
+)
+
+ConvertCurrencyResponse = TypedDict(
+    "ConvertCurrencyResponse",
+    {
+        "from": str,
+        "to": str,
+        "amount": float,
+        "convertedAmount": float,
+        "rate": float,
+    },
+)
+
+
+class PaginatedMeta(TypedDict):
+    total: int
+    page: int
+    limit: int
+    totalPages: int
+
+
+class ListDeliveriesResponse(TypedDict):
+    data: list[DeliveryDetail]
+    meta: PaginatedMeta
+
+
+class WebhookEnvelope(TypedDict):
+    event: WebhookEventName
+    data: dict[str, object]

waysdrop-1.0.0/src/waysdrop/webhooks.py

@@ -0,0 +1,38 @@
+import json
+from typing import Union
+
+from waysdrop.types import WebhookEnvelope, WebhookEventName
+
+
+def verify_signature(
+    raw_body: Union[bytes, str],
+    signature_header: str | None,
+    api_key: str,
+) -> bool:
+    if not signature_header:
+        return False
+    body = raw_body if isinstance(raw_body, bytes) else raw_body.encode("utf-8")
+    import hmac
+    import hashlib
+
+    expected = hmac.new(api_key.encode("utf-8"), body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, signature_header)
+
+
+def parse_webhook(raw_body: Union[bytes, str]) -> WebhookEnvelope:
+    text = raw_body if isinstance(raw_body, str) else raw_body.decode("utf-8")
+    payload = json.loads(text)
+    if "event" not in payload or "data" not in payload:
+        raise ValueError("Invalid webhook payload: expected { event, data }")
+    return {
+        "event": payload["event"],
+        "data": payload["data"],
+    }
+
+
+def parse_webhook_event(raw_body: Union[bytes, str]) -> WebhookEnvelope:
+    return parse_webhook(raw_body)
+
+
+def is_webhook_event(envelope: WebhookEnvelope, event: WebhookEventName) -> bool:
+    return envelope["event"] == event

waysdrop-1.0.0/tests/fixtures/signature.json

@@ -0,0 +1,16 @@
+{
+    "apiKey": "wsp_staging_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "payload": {
+        "event": "p2p.delivery.created",
+        "data": {
+            "status": "REQUEST_CREATED",
+            "trackingId": "P2P-TEST-001",
+            "deliveryId": "550e8400-e29b-41d4-a716-446655440000",
+            "p2pDeliveryId": "660e8400-e29b-41d4-a716-446655440001"
+        }
+    },
+    "rawBody": "{\"event\":\"p2p.delivery.created\",\"data\":{\"status\":\"REQUEST_CREATED\",\"trackingId\":\"P2P-TEST-001\",\"deliveryId\":\"550e8400-e29b-41d4-a716-446655440000\",\"p2pDeliveryId\":\"660e8400-e29b-41d4-a716-446655440001\"}}",
+    "signature": "7f180019583a154433a360d5f4ee6e3470e78c01e94c6879783641c024c28af3",
+    "algorithm": "HMAC-SHA256",
+    "signInput": "JSON.stringify(payload) using the exact raw body bytes"
+}

waysdrop-1.0.0/tests/run_tests.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+import sys
+import json
+import importlib.util
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SRC = ROOT / "src" / "waysdrop"
+
+
+def load_module(name: str, filename: str):
+    spec = importlib.util.spec_from_file_location(name, SRC / filename)
+    module = importlib.util.module_from_spec(spec)
+    assert spec.loader is not None
+    spec.loader.exec_module(module)
+    return module
+
+
+def bootstrap_package() -> None:
+    pkg = importlib.util.module_from_spec(
+        importlib.util.spec_from_loader("waysdrop", loader=None)
+    )
+    sys.modules["waysdrop"] = pkg
+    types_mod = load_module("waysdrop.types", "types.py")
+    sys.modules["waysdrop.types"] = types_mod
+
+
+bootstrap_package()
+errors = load_module("waysdrop_errors", "errors.py")
+webhooks = load_module("waysdrop_webhooks", "webhooks.py")
+
+FIXTURE = json.loads(
+    (Path(__file__).resolve().parent / "fixtures" / "signature.json").read_text()
+)
+
+
+def test_validate_api_key():
+    try:
+        errors.validate_api_key("bad")
+        raise AssertionError("expected ValueError")
+    except ValueError:
+        pass
+    errors.validate_api_key(FIXTURE["apiKey"])
+
+
+def test_infer_base_url():
+    assert errors.infer_base_url(FIXTURE["apiKey"]) == "https://staging-api.waysdrop.com"
+
+
+def test_verify_signature():
+    assert webhooks.verify_signature(FIXTURE["rawBody"], FIXTURE["signature"], FIXTURE["apiKey"])
+    assert not webhooks.verify_signature(FIXTURE["rawBody"], "bad", FIXTURE["apiKey"])
+
+
+def test_parse_webhook():
+    parsed = webhooks.parse_webhook(FIXTURE["rawBody"])
+    assert parsed["event"] == "p2p.delivery.created"
+    assert parsed["data"]["trackingId"] == "P2P-TEST-001"
+
+
+def test_waysdrop_error():
+    err = errors.WaysdropError("quota", status_code=429, quota={"limit": 1000})
+    assert err.status_code == 429
+
+
+if __name__ == "__main__":
+    test_validate_api_key()
+    test_infer_base_url()
+    test_verify_signature()
+    test_parse_webhook()
+    test_waysdrop_error()
+    print("all tests passed")

waysdrop-1.0.0/tests/test_client.py

@@ -0,0 +1,38 @@
+import json
+from pathlib import Path
+
+import pytest
+
+from waysdrop.errors import WaysdropError, infer_base_url, validate_api_key
+from waysdrop.webhooks import parse_webhook, verify_signature
+
+FIXTURES = Path(__file__).resolve().parent / "fixtures"
+SIGNATURE = json.loads((FIXTURES / "signature.json").read_text())
+
+
+def test_validate_api_key():
+    with pytest.raises(ValueError, match="Invalid API key"):
+        validate_api_key("bad")
+    validate_api_key(SIGNATURE["apiKey"])
+
+
+def test_infer_base_url():
+    assert infer_base_url(SIGNATURE["apiKey"]) == "https://staging-api.waysdrop.com"
+    assert infer_base_url("wsp_live_" + "a" * 64) == "https://api.waysdrop.com"
+
+
+def test_verify_signature():
+    assert verify_signature(SIGNATURE["rawBody"], SIGNATURE["signature"], SIGNATURE["apiKey"])
+    assert not verify_signature(SIGNATURE["rawBody"], "bad", SIGNATURE["apiKey"])
+
+
+def test_parse_webhook():
+    parsed = parse_webhook(SIGNATURE["rawBody"])
+    assert parsed["event"] == "p2p.delivery.created"
+    assert parsed["data"]["trackingId"] == "P2P-TEST-001"
+
+
+def test_waysdrop_error():
+    err = WaysdropError("quota", status_code=429, quota={"limit": 1000})
+    assert err.status_code == 429
+    assert err.quota == {"limit": 1000}