allowances-api 0.1.0__tar.gz

allowances_api-0.1.0/.gitignore

@@ -0,0 +1,49 @@
+# Byte-compiled Python and interpreter caches
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution and packaging artifacts
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+wheels/
+pip-wheel-metadata/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Test, coverage, type-checker, and linter caches
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.tox/
+.nox/
+.mypy_cache/
+.pyright/
+.ruff_cache/
+.hypothesis/
+
+# IDE and editor settings
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Environment files and local secrets
+.env
+.env.*
+!.env.example
+!.env.dist
+
+# Operating-system metadata
+.DS_Store
+Thumbs.db

allowances_api-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Allowances API
+
+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.
+

allowances_api-0.1.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: allowances-api
+Version: 0.1.0
+Summary: Official Python SDK for the Allowances API
+Project-URL: Homepage, https://www.allowancesapi.com
+Project-URL: Documentation, https://www.allowancesapi.com/docs
+Project-URL: Repository, https://github.com/allowances-api/allowances-api-python
+Project-URL: Issues, https://github.com/allowances-api/allowances-api-python/issues
+Author-email: Allowances API <contact@allowancesapi.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: allowances,dssr,dtmo,gsa,per-diem,travel
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.25
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Requires-Dist: twine>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Allowances API Python SDK
+
+The official Python client for [Allowances API](https://www.allowancesapi.com), a normalized API for U.S. government travel and overseas compensation data.
+
+The API brings together rates published by three different government sources:
+
+- **DSSR** — overseas post allowance (COLA), hardship differential, danger pay, education allowance, living quarters allowance, and foreign per diem.
+- **DTMO** — military per diem for CONUS and OCONUS locations.
+- **GSA** — civilian CONUS per diem, mileage reimbursement, and Fleet vehicle leasing rates.
+
+This SDK handles API-key authentication, URL construction, parameter serialization, response decoding, and useful Python exceptions. It is useful for travel platforms, expense systems, payroll and mobility tools, government contractors, and internal applications that need current or historical allowance data without maintaining scrapers for several unrelated sources.
+
+## Installation
+
+```bash
+pip install allowances-api
+```
+
+Python 3.9 or newer is required.
+
+## Authentication
+
+Create an API key at [allowancesapi.com](https://www.allowancesapi.com), then provide it directly:
+
+```python
+from allowances_api import AllowancesClient
+
+client = AllowancesClient("ak_live_your_key")
+```
+
+For applications, keeping the key in an environment variable is preferable. The client will find your api key if you set it explicitely as ALLOWANCES_API_KEY.
+
+```bash
+export ALLOWANCES_API_KEY="ak_live_your_key"
+```
+
+```python
+from allowances_api import AllowancesClient
+
+client = AllowancesClient()  # reads ALLOWANCES_API_KEY
+```
+
+Every request sends the key in the API's `X-API-Key` header. Do not embed a secret API key in browser or mobile client code.
+
+## Quick start
+
+Use the client as a context manager so its connection pool is closed automatically:
+
+```python
+from datetime import date
+from allowances_api import AllowancesClient
+
+with AllowancesClient() as client:
+    # Overseas allowances for Nairobi
+    kenya = client.dssr.allowances_by_location(
+        "KE",
+        "Nairobi",
+        date=date.today(),
+        type=["cola", "hardship", "danger_pay"],
+    )
+
+    # Military OCONUS per diem
+    australia = client.dtmo.perdiem_oconus("AU", query="Adelaide")
+
+    # Civilian CONUS per diem
+    albany = client.gsa.perdiem_by_state("NY", location="Albany")
+```
+
+Responses are returned as decoded dictionaries or lists, matching the documented JSON response exactly.
+
+## Common use cases
+
+### Look up an overseas post allowance and calculate COLA
+
+```python
+rates = client.dssr.allowances_by_postcode("BE", "10112", types=["cola"])
+
+estimate = client.dssr.calculate_cola(
+    "10112",
+    family_size=4,
+    base_salary=100_000,
+)
+print(estimate["annual_cola"], estimate["biweekly_cola"])
+```
+
+### Retrieve per diem by source
+
+```python
+# Department of State foreign per diem
+dssr = client.dssr.perdiem_by_location("KE", "Nairobi")
+
+# Defense Travel Management Office military rates
+dtmo = client.dtmo.perdiem_conus("US-CO", query="Aspen")
+
+# General Services Administration civilian rates
+gsa = client.gsa.perdiem_by_zipcode("12207")
+```
+
+### Mileage and GSA Fleet rates
+
+```python
+mileage = client.gsa.mileage(mileage_type="automobile")
+fleet = client.gsa.vehicle_rates("standard", "10B", year=2026)
+```
+
+### Browse locations
+
+```python
+countries = client.dssr.countries(query="United")
+dssr_locations = client.dssr.country_locations("DE")
+dtmo_locations = client.dtmo.locations_oconus("AU", location="Sydney")
+states = client.gsa.states()
+destinations = client.gsa.destinations(limit=50)
+```
+
+## Errors
+
+The SDK maps common status codes to specific exceptions:
+
+```python
+from allowances_api import ForbiddenError, NotFoundError, RateLimitError
+
+try:
+    result = client.dssr.perdiem("XX")
+except NotFoundError as exc:
+    print(exc.status_code, exc.message, exc.request_id)
+except ForbiddenError:
+    print("This request is not included in the current plan")
+except RateLimitError:
+    print("Request limit reached")
+```
+
+Available exception classes are `AuthenticationError`, `ForbiddenError`, `NotFoundError`, `ValidationError`, `RateLimitError`, `TransportError`, and the base `AllowancesAPIError`.
+
+## Configuration
+
+Use a different endpoint or timeout for local development and testing:
+
+```python
+client = AllowancesClient(
+    "test-key",
+    base_url="http://localhost:8000/v1",
+    timeout=10,
+)
+```
+
+An existing `httpx.Client` can be injected for custom transports, proxies, telemetry, or testing:
+
+```python
+import httpx
+from allowances_api import AllowancesClient
+
+transport = httpx.HTTPTransport(retries=2)
+http = httpx.Client(base_url="https://api.allowancesapi.com/v1", transport=transport)
+client = AllowancesClient("ak_live_your_key", http_client=http)
+```
+
+When injecting a client, its lifecycle remains owned by the caller.
+
+## Endpoint mapping
+
+SDK methods follow the API's three source groups:
+
+- `client.dssr`: allowances, per diem, COLA calculator, countries, and locations.
+- `client.dtmo`: CONUS/OCONUS per diem, search, and locations.
+- `client.gsa`: destination/state/ZIP per diem, ZIP and county metadata, mileage, and vehicle rates.
+
+See the complete [API documentation](https://www.allowancesapi.com/docs) for response fields, plan limits, and data-source details.
+
+## Development and publishing
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e '.[dev]'
+pytest
+ruff check .
+python -m build
+twine check dist/*
+```
+
+Publish a release after updating the version in `pyproject.toml` and `src/allowances_api/__init__.py`:
+
+```bash
+twine upload dist/*
+```
+
+## License
+
+MIT
+

allowances_api-0.1.0/README.md

@@ -0,0 +1,191 @@
+# Allowances API Python SDK
+
+The official Python client for [Allowances API](https://www.allowancesapi.com), a normalized API for U.S. government travel and overseas compensation data.
+
+The API brings together rates published by three different government sources:
+
+- **DSSR** — overseas post allowance (COLA), hardship differential, danger pay, education allowance, living quarters allowance, and foreign per diem.
+- **DTMO** — military per diem for CONUS and OCONUS locations.
+- **GSA** — civilian CONUS per diem, mileage reimbursement, and Fleet vehicle leasing rates.
+
+This SDK handles API-key authentication, URL construction, parameter serialization, response decoding, and useful Python exceptions. It is useful for travel platforms, expense systems, payroll and mobility tools, government contractors, and internal applications that need current or historical allowance data without maintaining scrapers for several unrelated sources.
+
+## Installation
+
+```bash
+pip install allowances-api
+```
+
+Python 3.9 or newer is required.
+
+## Authentication
+
+Create an API key at [allowancesapi.com](https://www.allowancesapi.com), then provide it directly:
+
+```python
+from allowances_api import AllowancesClient
+
+client = AllowancesClient("ak_live_your_key")
+```
+
+For applications, keeping the key in an environment variable is preferable. The client will find your api key if you set it explicitely as ALLOWANCES_API_KEY.
+
+```bash
+export ALLOWANCES_API_KEY="ak_live_your_key"
+```
+
+```python
+from allowances_api import AllowancesClient
+
+client = AllowancesClient()  # reads ALLOWANCES_API_KEY
+```
+
+Every request sends the key in the API's `X-API-Key` header. Do not embed a secret API key in browser or mobile client code.
+
+## Quick start
+
+Use the client as a context manager so its connection pool is closed automatically:
+
+```python
+from datetime import date
+from allowances_api import AllowancesClient
+
+with AllowancesClient() as client:
+    # Overseas allowances for Nairobi
+    kenya = client.dssr.allowances_by_location(
+        "KE",
+        "Nairobi",
+        date=date.today(),
+        type=["cola", "hardship", "danger_pay"],
+    )
+
+    # Military OCONUS per diem
+    australia = client.dtmo.perdiem_oconus("AU", query="Adelaide")
+
+    # Civilian CONUS per diem
+    albany = client.gsa.perdiem_by_state("NY", location="Albany")
+```
+
+Responses are returned as decoded dictionaries or lists, matching the documented JSON response exactly.
+
+## Common use cases
+
+### Look up an overseas post allowance and calculate COLA
+
+```python
+rates = client.dssr.allowances_by_postcode("BE", "10112", types=["cola"])
+
+estimate = client.dssr.calculate_cola(
+    "10112",
+    family_size=4,
+    base_salary=100_000,
+)
+print(estimate["annual_cola"], estimate["biweekly_cola"])
+```
+
+### Retrieve per diem by source
+
+```python
+# Department of State foreign per diem
+dssr = client.dssr.perdiem_by_location("KE", "Nairobi")
+
+# Defense Travel Management Office military rates
+dtmo = client.dtmo.perdiem_conus("US-CO", query="Aspen")
+
+# General Services Administration civilian rates
+gsa = client.gsa.perdiem_by_zipcode("12207")
+```
+
+### Mileage and GSA Fleet rates
+
+```python
+mileage = client.gsa.mileage(mileage_type="automobile")
+fleet = client.gsa.vehicle_rates("standard", "10B", year=2026)
+```
+
+### Browse locations
+
+```python
+countries = client.dssr.countries(query="United")
+dssr_locations = client.dssr.country_locations("DE")
+dtmo_locations = client.dtmo.locations_oconus("AU", location="Sydney")
+states = client.gsa.states()
+destinations = client.gsa.destinations(limit=50)
+```
+
+## Errors
+
+The SDK maps common status codes to specific exceptions:
+
+```python
+from allowances_api import ForbiddenError, NotFoundError, RateLimitError
+
+try:
+    result = client.dssr.perdiem("XX")
+except NotFoundError as exc:
+    print(exc.status_code, exc.message, exc.request_id)
+except ForbiddenError:
+    print("This request is not included in the current plan")
+except RateLimitError:
+    print("Request limit reached")
+```
+
+Available exception classes are `AuthenticationError`, `ForbiddenError`, `NotFoundError`, `ValidationError`, `RateLimitError`, `TransportError`, and the base `AllowancesAPIError`.
+
+## Configuration
+
+Use a different endpoint or timeout for local development and testing:
+
+```python
+client = AllowancesClient(
+    "test-key",
+    base_url="http://localhost:8000/v1",
+    timeout=10,
+)
+```
+
+An existing `httpx.Client` can be injected for custom transports, proxies, telemetry, or testing:
+
+```python
+import httpx
+from allowances_api import AllowancesClient
+
+transport = httpx.HTTPTransport(retries=2)
+http = httpx.Client(base_url="https://api.allowancesapi.com/v1", transport=transport)
+client = AllowancesClient("ak_live_your_key", http_client=http)
+```
+
+When injecting a client, its lifecycle remains owned by the caller.
+
+## Endpoint mapping
+
+SDK methods follow the API's three source groups:
+
+- `client.dssr`: allowances, per diem, COLA calculator, countries, and locations.
+- `client.dtmo`: CONUS/OCONUS per diem, search, and locations.
+- `client.gsa`: destination/state/ZIP per diem, ZIP and county metadata, mileage, and vehicle rates.
+
+See the complete [API documentation](https://www.allowancesapi.com/docs) for response fields, plan limits, and data-source details.
+
+## Development and publishing
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e '.[dev]'
+pytest
+ruff check .
+python -m build
+twine check dist/*
+```
+
+Publish a release after updating the version in `pyproject.toml` and `src/allowances_api/__init__.py`:
+
+```bash
+twine upload dist/*
+```
+
+## License
+
+MIT
+

allowances_api-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "allowances-api"
+version = "0.1.0"
+description = "Official Python SDK for the Allowances API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "Allowances API", email = "contact@allowancesapi.com" }]
+keywords = ["allowances", "per-diem", "dssr", "dtmo", "gsa", "travel"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = ["httpx>=0.25,<1"]
+
+[project.urls]
+Homepage = "https://www.allowancesapi.com"
+Documentation = "https://www.allowancesapi.com/docs"
+Repository = "https://github.com/allowances-api/allowances-api-python"
+Issues = "https://github.com/allowances-api/allowances-api-python/issues"
+
+[project.optional-dependencies]
+dev = ["build>=1.2", "pytest>=8", "pytest-cov>=5", "ruff>=0.9", "twine>=6"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/allowances_api"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=allowances_api --cov-branch --cov-report=term-missing --cov-fail-under=95"
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"

allowances_api-0.1.0/src/allowances_api/__init__.py

@@ -0,0 +1,26 @@
+"""Python SDK for the Allowances API."""
+
+from .client import AllowancesClient
+from .exceptions import (
+    AllowancesAPIError,
+    AuthenticationError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    TransportError,
+    ValidationError,
+)
+
+__all__ = [
+    "AllowancesClient",
+    "AllowancesAPIError",
+    "AuthenticationError",
+    "ForbiddenError",
+    "NotFoundError",
+    "RateLimitError",
+    "TransportError",
+    "ValidationError",
+]
+
+__version__ = "0.1.0"
+

allowances_api-0.1.0/src/allowances_api/_utils.py

@@ -0,0 +1,24 @@
+from datetime import date, datetime
+from enum import Enum
+from typing import Any, Dict, Mapping, Optional
+
+
+def serialize(value: Any) -> Any:
+    if isinstance(value, (date, datetime)):
+        return value.isoformat()
+    if isinstance(value, Enum):
+        return value.value
+    if isinstance(value, (list, tuple, set)):
+        return [serialize(item) for item in value]
+    return value
+
+
+def query_params(**values: Any) -> Dict[str, Any]:
+    return {key: serialize(value) for key, value in values.items() if value is not None}
+
+
+def merge_params(params: Optional[Mapping[str, Any]], **values: Any) -> Dict[str, Any]:
+    merged = dict(params or {})
+    merged.update(query_params(**values))
+    return merged
+

allowances_api-0.1.0/src/allowances_api/client.py

@@ -0,0 +1,100 @@
+"""HTTP client and authentication for the Allowances API."""
+
+import os
+from typing import Any, Mapping, Optional
+
+import httpx
+
+from .exceptions import (
+    AllowancesAPIError,
+    AuthenticationError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    TransportError,
+    ValidationError,
+    error_details,
+)
+from .resources import DSSRResource, DTMOResource, GSAResource
+
+DEFAULT_BASE_URL = "https://api.allowancesapi.com/v1"
+
+
+class AllowancesClient:
+    """Authenticated synchronous client for all public Allowances API endpoints."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        key = api_key or os.getenv("ALLOWANCES_API_KEY")
+        if not key:
+            raise ValueError("Pass api_key or set the ALLOWANCES_API_KEY environment variable")
+
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            headers={"X-API-Key": key, "User-Agent": "allowances-api-python/0.1.0"},
+        )
+        if http_client is not None:
+            self._http.headers["X-API-Key"] = key
+            self._http.headers.setdefault("User-Agent", "allowances-api-python/0.1.0")
+
+        self.dssr = DSSRResource(self)
+        self.dtmo = DTMOResource(self)
+        self.gsa = GSAResource(self)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+    ) -> Any:
+        try:
+            response = self._http.request(method, path, params=params)
+        except httpx.HTTPError as exc:
+            raise TransportError(str(exc)) from exc
+
+        if response.is_success:
+            if response.status_code == 204 or not response.content:
+                return None
+            return response.json()
+
+        try:
+            payload = response.json()
+        except ValueError:
+            payload = None
+        message, request_id = error_details(payload)
+        error_type = {
+            401: AuthenticationError,
+            403: ForbiddenError,
+            404: NotFoundError,
+            422: ValidationError,
+            429: RateLimitError,
+        }.get(response.status_code, AllowancesAPIError)
+        raise error_type(
+            message,
+            status_code=response.status_code,
+            request_id=request_id,
+            response=response,
+        )
+
+    def get(self, path: str, *, params: Optional[Mapping[str, Any]] = None) -> Any:
+        return self.request("GET", path, params=params)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._http.close()
+
+    def __enter__(self) -> "AllowancesClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+

allowances_api-0.1.0/src/allowances_api/exceptions.py

@@ -0,0 +1,60 @@
+"""Exceptions raised by the Allowances API client."""
+
+from typing import Any, Mapping, Optional
+
+
+class AllowancesAPIError(Exception):
+    """An error response returned by the Allowances API."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        request_id: Optional[str] = None,
+        response: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.request_id = request_id
+        self.response = response
+
+
+class AuthenticationError(AllowancesAPIError):
+    """The API key is missing or invalid."""
+
+
+class ForbiddenError(AllowancesAPIError):
+    """The current plan cannot access the requested resource."""
+
+
+class NotFoundError(AllowancesAPIError):
+    """The requested data was not found."""
+
+
+class ValidationError(AllowancesAPIError):
+    """One or more request parameters are invalid."""
+
+
+class RateLimitError(AllowancesAPIError):
+    """The account's request limit was exceeded."""
+
+
+class TransportError(AllowancesAPIError):
+    """The request could not reach the API."""
+
+
+def error_details(payload: Any) -> tuple[str, Optional[str]]:
+    """Extract the API's message and request ID from supported error envelopes."""
+    if not isinstance(payload, Mapping):
+        return "Allowances API request failed", None
+
+    detail = payload.get("detail", payload)
+    if isinstance(detail, Mapping):
+        return str(detail.get("message") or detail.get("detail") or detail), detail.get("request_id")
+    if isinstance(detail, list):
+        messages = [str(item.get("msg", item)) if isinstance(item, Mapping) else str(item) for item in detail]
+        return "; ".join(messages), None
+    return str(detail), None
+

allowances_api-0.1.0/src/allowances_api/py.typed

@@ -0,0 +1 @@
+

allowances_api-0.1.0/src/allowances_api/resources.py

@@ -0,0 +1,153 @@
+"""Resource clients mirroring the public v1 API routes."""
+
+from datetime import date
+from typing import TYPE_CHECKING, Any, Iterable, Optional, Union
+from urllib.parse import quote
+
+from ._utils import query_params
+
+if TYPE_CHECKING:
+    from .client import AllowancesClient
+
+DateLike = Union[str, date]
+
+
+def segment(value: Any) -> str:
+    return quote(str(value), safe="")
+
+
+class Resource:
+    def __init__(self, client: "AllowancesClient") -> None:
+        self._client = client
+
+    def _get(self, path: str, **params: Any) -> Any:
+        # Friendly Python names for API parameters whose wire names are terse or singular.
+        if "types" in params:
+            params["type"] = params.pop("types")
+        if "query" in params:
+            params["q"] = params.pop("query")
+        return self._client.get(path, params=query_params(**params))
+
+
+class DSSRResource(Resource):
+    def allowances(
+        self, country: str, *, date: Optional[DateLike] = None,
+        types: Optional[Iterable[str]] = None, verification_url: bool = False,
+    ) -> Any:
+        return self._get(f"/dssr/allowances/{segment(country)}", date=date, type=types,
+                         verification_url=verification_url)
+
+    def allowances_by_location(self, country: str, location: str, **params: Any) -> Any:
+        return self._get(f"/dssr/allowances/{segment(country)}/location/{segment(location)}", **params)
+
+    def allowances_by_postcode(self, country: str, postcode: Union[str, int], **params: Any) -> Any:
+        return self._get(f"/dssr/allowances/{segment(country)}/postcode/{segment(postcode)}", **params)
+
+    def perdiem(self, country: str, **params: Any) -> Any:
+        return self._get(f"/dssr/perdiem/{segment(country)}", **params)
+
+    def perdiem_by_location(self, country: str, location: str, **params: Any) -> Any:
+        return self._get(f"/dssr/perdiem/{segment(country)}/location/{segment(location)}", **params)
+
+    def perdiem_by_postcode(self, country: str, postcode: Union[str, int], **params: Any) -> Any:
+        return self._get(f"/dssr/perdiem/{segment(country)}/postcode/{segment(postcode)}", **params)
+
+    def search_perdiem(self, query: str, *, date: Optional[DateLike] = None) -> Any:
+        return self._get("/dssr/perdiem/search", q=query, date=date)
+
+    def locations(self, *, query: Optional[str] = None, offset: int = 0, limit: int = 10) -> Any:
+        return self._get("/dssr/locations", q=query, offset=offset, limit=limit)
+
+    def countries(self, *, query: Optional[str] = None, offset: int = 0, limit: int = 20) -> Any:
+        return self._get("/dssr/countries", q=query, offset=offset, limit=limit)
+
+    def country(self, country: str) -> Any:
+        return self._get(f"/dssr/country/{segment(country)}")
+
+    def country_locations(self, country: str) -> Any:
+        return self._get(f"/dssr/country/{segment(country)}/locations")
+
+    def calculate_cola(
+        self, postcode: Union[str, int], *, family_size: int, base_salary: int,
+        date: Optional[DateLike] = None,
+    ) -> Any:
+        return self._get(f"/dssr/cola-calculator/postcode/{segment(postcode)}",
+                         family_size=family_size, base_salary=base_salary, date=date)
+
+
+class DTMOResource(Resource):
+    def perdiem_conus(
+        self, state: str, *, date: Optional[DateLike] = None, year: Optional[int] = None,
+        query: Optional[str] = None, verification_url: bool = False,
+        offset: int = 0, limit: int = 50,
+    ) -> Any:
+        return self._get(f"/dtmo/perdiem/conus/{segment(state)}", date=date, year=year, q=query,
+                         verification_url=verification_url, offset=offset, limit=limit)
+
+    def perdiem_oconus(self, country: str, **params: Any) -> Any:
+        return self._get(f"/dtmo/perdiem/oconus/{segment(country)}", **params)
+
+    def search_perdiem(
+        self, query: str, *, date: Optional[DateLike] = None, year: Optional[int] = None,
+        verification_url: bool = False,
+    ) -> Any:
+        return self._get("/dtmo/perdiem/search", q=query, date=date, year=year,
+                         verification_url=verification_url)
+
+    def locations_conus(self, state: str) -> Any:
+        return self._get(f"/dtmo/locations/conus/{segment(state)}")
+
+    def locations_oconus(self, country: str, *, location: Optional[str] = None) -> Any:
+        return self._get(f"/dtmo/locations/oconus/{segment(country)}", location=location)
+
+
+class GSAResource(Resource):
+    def perdiem_by_destination(self, destination_id: int, **params: Any) -> Any:
+        return self._get(f"/gsa/perdiem/destination/{destination_id}", **params)
+
+    def perdiem_by_state(self, state: str, **params: Any) -> Any:
+        return self._get(f"/gsa/perdiem/state/{segment(state)}", **params)
+
+    def perdiem_by_state_year(self, state: str, year: int, **params: Any) -> Any:
+        return self._get(f"/gsa/perdiem/state/{segment(state)}/year/{year}", **params)
+
+    def perdiem_by_zipcode(self, zipcode: Union[str, int], **params: Any) -> Any:
+        return self._get(f"/gsa/perdiem/zipcode/{segment(zipcode)}", **params)
+
+    def perdiem_by_zipcode_year(self, zipcode: Union[str, int], year: int, **params: Any) -> Any:
+        return self._get(f"/gsa/perdiem/zipcode/{segment(zipcode)}/year/{year}", **params)
+
+    def zipcodes(self, state: str, *, offset: int = 0, limit: int = 20) -> Any:
+        return self._get(f"/gsa/zipcodes/{segment(state)}", offset=offset, limit=limit)
+
+    def zipcode(self, zipcode: Union[str, int]) -> Any:
+        return self._get(f"/gsa/zipcode/{segment(zipcode)}")
+
+    def counties(
+        self, *, query: Optional[str] = None, state: Optional[str] = None,
+        offset: int = 0, limit: int = 20,
+    ) -> Any:
+        return self._get("/gsa/counties", q=query, state=state, offset=offset, limit=limit)
+
+    def destination(self, destination_id: int) -> Any:
+        return self._get(f"/gsa/destination/{destination_id}")
+
+    def destinations(self, *, offset: int = 0, limit: int = 100) -> Any:
+        return self._get("/gsa/destinations", offset=offset, limit=limit)
+
+    def states(self) -> Any:
+        return self._get("/gsa/states")
+
+    def mileage(
+        self, *, date: Optional[DateLike] = None, mileage_type: Optional[str] = None,
+        verification_url: bool = False,
+    ) -> Any:
+        return self._get("/gsa/mileage", date=date, type=mileage_type,
+                         verification_url=verification_url)
+
+    def vehicle_rates(
+        self, rate_type: str, sin: str, *, year: Optional[int] = None,
+        verification_url: bool = False,
+    ) -> Any:
+        return self._get(f"/gsa/vehicle-rates/{segment(rate_type)}/{segment(sin)}", year=year,
+                         verification_url=verification_url)

allowances_api-0.1.0/tests/test_client.py

@@ -0,0 +1,234 @@
+from datetime import date
+
+import httpx
+import pytest
+
+from allowances_api import (
+    AllowancesAPIError,
+    AllowancesClient,
+    AuthenticationError,
+    ForbiddenError,
+    NotFoundError,
+    RateLimitError,
+    TransportError,
+    ValidationError,
+)
+
+
+def make_client(handler):
+    http = httpx.Client(
+        base_url="https://example.test/v1",
+        transport=httpx.MockTransport(handler),
+    )
+    return AllowancesClient("secret-key", http_client=http), http
+
+
+def test_authentication_and_dssr_parameter_serialization():
+    def handler(request):
+        assert request.headers["X-API-Key"] == "secret-key"
+        assert request.url.path == "/v1/dssr/allowances/KE/location/Nairobi"
+        assert request.url.params.get("date") == "2026-01-02"
+        assert request.url.params.get_list("type") == ["cola", "hardship"]
+        return httpx.Response(200, json={"effective_date": "2026-01-01", "results": []})
+
+    client, http = make_client(handler)
+    try:
+        payload = client.dssr.allowances_by_location(
+            "KE", "Nairobi", date=date(2026, 1, 2), type=["cola", "hardship"]
+        )
+        assert payload["results"] == []
+    finally:
+        http.close()
+
+
+def test_all_resource_groups_are_available():
+    paths = []
+
+    def handler(request):
+        paths.append(request.url.path)
+        return httpx.Response(200, json={})
+
+    client, http = make_client(handler)
+    try:
+        client.dssr.country("BE")
+        client.dtmo.perdiem_oconus("AU")
+        client.gsa.vehicle_rates("standard", "10B", year=2026)
+    finally:
+        http.close()
+
+    assert paths == [
+        "/v1/dssr/country/BE",
+        "/v1/dtmo/perdiem/oconus/AU",
+        "/v1/gsa/vehicle-rates/standard/10B",
+    ]
+
+
+@pytest.mark.parametrize(
+    ("status_code", "exception"),
+    [
+        (401, AuthenticationError),
+        (403, ForbiddenError),
+        (404, NotFoundError),
+        (422, ValidationError),
+        (429, RateLimitError),
+        (500, AllowancesAPIError),
+    ],
+)
+def test_structured_api_errors(status_code, exception):
+    def handler(request):
+        return httpx.Response(
+            status_code,
+            json={"detail": {"message": "No access", "request_id": "req_123"}},
+        )
+
+    client, http = make_client(handler)
+    try:
+        with pytest.raises(exception) as raised:
+            client.gsa.mileage(date="2020-01-01")
+        assert raised.value.status_code == status_code
+        assert raised.value.request_id == "req_123"
+        assert str(raised.value) == "No access"
+    finally:
+        http.close()
+
+
+def test_api_key_can_come_from_environment(monkeypatch):
+    monkeypatch.setenv("ALLOWANCES_API_KEY", "environment-key")
+
+    def handler(request):
+        assert request.headers["X-API-Key"] == "environment-key"
+        return httpx.Response(200, json=[])
+
+    http = httpx.Client(base_url="https://example.test/v1", transport=httpx.MockTransport(handler))
+    client = AllowancesClient(http_client=http)
+    try:
+        assert client.gsa.states() == []
+    finally:
+        http.close()
+
+
+def test_missing_api_key_is_rejected(monkeypatch):
+    monkeypatch.delenv("ALLOWANCES_API_KEY", raising=False)
+    with pytest.raises(ValueError, match="ALLOWANCES_API_KEY"):
+        AllowancesClient()
+
+
+@pytest.mark.parametrize(
+    ("payload", "message", "request_id"),
+    [
+        ({"detail": "Plain error"}, "Plain error", None),
+        ({"detail": {"detail": "Nested error"}}, "Nested error", None),
+        ({"detail": {"code": "unknown"}}, "{'code': 'unknown'}", None),
+        ({"detail": [{"msg": "Bad country"}, {"msg": "Bad date"}]},
+         "Bad country; Bad date", None),
+        ({"detail": ["First", "Second"]}, "First; Second", None),
+        ({"message": "Top level", "request_id": "req_top"}, "Top level", "req_top"),
+    ],
+)
+def test_supported_error_envelopes(payload, message, request_id):
+    def handler(request):
+        return httpx.Response(400, json=payload)
+
+    client, http = make_client(handler)
+    try:
+        with pytest.raises(AllowancesAPIError) as raised:
+            client.gsa.states()
+        assert raised.value.message == message
+        assert raised.value.request_id == request_id
+        assert raised.value.response.status_code == 400
+    finally:
+        http.close()
+
+
+def test_non_json_error_uses_a_safe_fallback_message():
+    def handler(request):
+        return httpx.Response(502, text="upstream exploded")
+
+    client, http = make_client(handler)
+    try:
+        with pytest.raises(AllowancesAPIError, match="Allowances API request failed"):
+            client.gsa.states()
+    finally:
+        http.close()
+
+
+@pytest.mark.parametrize("status_code", [204, 205])
+def test_empty_success_response_returns_none(status_code):
+    def handler(request):
+        return httpx.Response(status_code)
+
+    client, http = make_client(handler)
+    try:
+        assert client.get("/empty") is None
+    finally:
+        http.close()
+
+
+def test_malformed_json_success_is_exposed_to_the_caller():
+    def handler(request):
+        return httpx.Response(200, content=b"not-json", headers={"content-type": "application/json"})
+
+    client, http = make_client(handler)
+    try:
+        with pytest.raises(ValueError):
+            client.gsa.states()
+    finally:
+        http.close()
+
+
+def test_transport_errors_are_wrapped():
+    def handler(request):
+        raise httpx.ConnectError("connection refused", request=request)
+
+    client, http = make_client(handler)
+    try:
+        with pytest.raises(TransportError, match="connection refused") as raised:
+            client.gsa.states()
+        assert isinstance(raised.value.__cause__, httpx.ConnectError)
+    finally:
+        http.close()
+
+
+def test_explicit_key_takes_precedence_over_environment(monkeypatch):
+    monkeypatch.setenv("ALLOWANCES_API_KEY", "environment-key")
+
+    def handler(request):
+        assert request.headers["X-API-Key"] == "explicit-key"
+        return httpx.Response(200, json={})
+
+    http = httpx.Client(base_url="https://example.test/v1", transport=httpx.MockTransport(handler))
+    client = AllowancesClient("explicit-key", http_client=http)
+    try:
+        client.gsa.states()
+    finally:
+        http.close()
+
+
+def test_injected_http_client_is_not_closed_by_sdk():
+    http = httpx.Client(
+        base_url="https://example.test/v1",
+        transport=httpx.MockTransport(lambda request: httpx.Response(200, json={})),
+    )
+    client = AllowancesClient("key", http_client=http)
+    client.close()
+    assert not http.is_closed
+    http.close()
+
+
+def test_owned_http_client_is_closed_by_context_manager(monkeypatch):
+    created = []
+
+    class FakeHTTPClient:
+        def __init__(self, **kwargs):
+            self.headers = dict(kwargs["headers"])
+            self.closed = False
+            created.append(self)
+
+        def close(self):
+            self.closed = True
+
+    monkeypatch.setattr(httpx, "Client", FakeHTTPClient)
+    with AllowancesClient("key", base_url="https://example.test/v1/") as client:
+        assert client._http.headers["X-API-Key"] == "key"
+        assert not created[0].closed
+    assert created[0].closed

allowances_api-0.1.0/tests/test_endpoints.py

@@ -0,0 +1,146 @@
+from datetime import date
+
+import httpx
+import pytest
+
+from allowances_api import AllowancesClient
+
+
+ENDPOINT_CASES = [
+    # DSSR
+    ("dssr_allowances", lambda c: c.dssr.allowances("KE", date=date(2026, 1, 2),
+     types=["cola", "hardship"], verification_url=True), "/v1/dssr/allowances/KE",
+     {"date": ["2026-01-02"], "type": ["cola", "hardship"], "verification_url": ["true"]}),
+    ("dssr_allowances_location", lambda c: c.dssr.allowances_by_location(
+        "CI", "Abidjan Plateau", types=["cola"]),
+     "/v1/dssr/allowances/CI/location/Abidjan%20Plateau", {"type": ["cola"]}),
+    ("dssr_allowances_postcode", lambda c: c.dssr.allowances_by_postcode(
+        "BE", 10112, date="2026-01-01"),
+     "/v1/dssr/allowances/BE/postcode/10112", {"date": ["2026-01-01"]}),
+    ("dssr_perdiem", lambda c: c.dssr.perdiem("KE", verification_url=True),
+     "/v1/dssr/perdiem/KE", {"verification_url": ["true"]}),
+    ("dssr_perdiem_location", lambda c: c.dssr.perdiem_by_location("KE", "Nairobi"),
+     "/v1/dssr/perdiem/KE/location/Nairobi", {}),
+    ("dssr_perdiem_postcode", lambda c: c.dssr.perdiem_by_postcode("BE", "10112"),
+     "/v1/dssr/perdiem/BE/postcode/10112", {}),
+    ("dssr_search", lambda c: c.dssr.search_perdiem("Nairobi", date="2026-01-01"),
+     "/v1/dssr/perdiem/search", {"q": ["Nairobi"], "date": ["2026-01-01"]}),
+    ("dssr_locations", lambda c: c.dssr.locations(query="Nai", offset=10, limit=20),
+     "/v1/dssr/locations", {"q": ["Nai"], "offset": ["10"], "limit": ["20"]}),
+    ("dssr_countries", lambda c: c.dssr.countries(query="United", offset=2, limit=50),
+     "/v1/dssr/countries", {"q": ["United"], "offset": ["2"], "limit": ["50"]}),
+    ("dssr_country", lambda c: c.dssr.country("GB"), "/v1/dssr/country/GB", {}),
+    ("dssr_country_locations", lambda c: c.dssr.country_locations("DE"),
+     "/v1/dssr/country/DE/locations", {}),
+    ("dssr_cola", lambda c: c.dssr.calculate_cola(
+        "10016", family_size=4, base_salary=100_000, date=date(2026, 1, 1)),
+     "/v1/dssr/cola-calculator/postcode/10016",
+     {"family_size": ["4"], "base_salary": ["100000"], "date": ["2026-01-01"]}),
+    # DTMO
+    ("dtmo_conus", lambda c: c.dtmo.perdiem_conus(
+        "US-CO", date="2026-01-01", year=2026, query="Aspen", verification_url=True,
+        offset=5, limit=10), "/v1/dtmo/perdiem/conus/US-CO",
+     {"date": ["2026-01-01"], "year": ["2026"], "q": ["Aspen"],
+      "verification_url": ["true"], "offset": ["5"], "limit": ["10"]}),
+    ("dtmo_oconus", lambda c: c.dtmo.perdiem_oconus("AU", query="Adelaide", year=2026),
+     "/v1/dtmo/perdiem/oconus/AU", {"q": ["Adelaide"], "year": ["2026"]}),
+    ("dtmo_search", lambda c: c.dtmo.search_perdiem(
+        "Aspen", date="2026-01-01", year=2026, verification_url=True),
+     "/v1/dtmo/perdiem/search",
+     {"q": ["Aspen"], "date": ["2026-01-01"], "year": ["2026"],
+      "verification_url": ["true"]}),
+    ("dtmo_locations_conus", lambda c: c.dtmo.locations_conus("US-CA"),
+     "/v1/dtmo/locations/conus/US-CA", {}),
+    ("dtmo_locations_oconus", lambda c: c.dtmo.locations_oconus("AU", location="Sydney"),
+     "/v1/dtmo/locations/oconus/AU", {"location": ["Sydney"]}),
+    # GSA
+    ("gsa_perdiem_destination", lambda c: c.gsa.perdiem_by_destination(
+        22, date="2026-01-01", verification_url=True),
+     "/v1/gsa/perdiem/destination/22", {"date": ["2026-01-01"], "verification_url": ["true"]}),
+    ("gsa_perdiem_state", lambda c: c.gsa.perdiem_by_state("NY", location="Albany"),
+     "/v1/gsa/perdiem/state/NY", {"location": ["Albany"]}),
+    ("gsa_perdiem_state_year", lambda c: c.gsa.perdiem_by_state_year(
+        "CA", 2026, location="Los Angeles", verification_url=True),
+     "/v1/gsa/perdiem/state/CA/year/2026",
+     {"location": ["Los Angeles"], "verification_url": ["true"]}),
+    ("gsa_perdiem_zipcode", lambda c: c.gsa.perdiem_by_zipcode(12207, date="2026-01-01"),
+     "/v1/gsa/perdiem/zipcode/12207", {"date": ["2026-01-01"]}),
+    ("gsa_perdiem_zipcode_year", lambda c: c.gsa.perdiem_by_zipcode_year(
+        "12207", 2026, verification_url=True),
+     "/v1/gsa/perdiem/zipcode/12207/year/2026", {"verification_url": ["true"]}),
+    ("gsa_zipcodes", lambda c: c.gsa.zipcodes("NY", offset=20, limit=40),
+     "/v1/gsa/zipcodes/NY", {"offset": ["20"], "limit": ["40"]}),
+    ("gsa_zipcode", lambda c: c.gsa.zipcode("12207"), "/v1/gsa/zipcode/12207", {}),
+    ("gsa_counties", lambda c: c.gsa.counties(query="Albany", state="NY", offset=1, limit=30),
+     "/v1/gsa/counties", {"q": ["Albany"], "state": ["NY"], "offset": ["1"], "limit": ["30"]}),
+    ("gsa_destination", lambda c: c.gsa.destination(22), "/v1/gsa/destination/22", {}),
+    ("gsa_destinations", lambda c: c.gsa.destinations(offset=5, limit=25),
+     "/v1/gsa/destinations", {"offset": ["5"], "limit": ["25"]}),
+    ("gsa_states", lambda c: c.gsa.states(), "/v1/gsa/states", {}),
+    ("gsa_mileage", lambda c: c.gsa.mileage(
+        date=date(2026, 1, 1), mileage_type="automobile", verification_url=True),
+     "/v1/gsa/mileage", {"date": ["2026-01-01"], "type": ["automobile"],
+                          "verification_url": ["true"]}),
+    ("gsa_vehicle_rates", lambda c: c.gsa.vehicle_rates(
+        "standard", "10B", year=2026, verification_url=True),
+     "/v1/gsa/vehicle-rates/standard/10B", {"year": ["2026"], "verification_url": ["true"]}),
+]
+
+
+@pytest.mark.parametrize(("name", "invoke", "expected_path", "expected_params"), ENDPOINT_CASES,
+                         ids=[case[0] for case in ENDPOINT_CASES])
+def test_endpoint_contract(name, invoke, expected_path, expected_params):
+    seen = []
+
+    def handler(request):
+        seen.append(request)
+        return httpx.Response(200, json={"endpoint": name})
+
+    http = httpx.Client(base_url="https://example.test/v1", transport=httpx.MockTransport(handler))
+    client = AllowancesClient("test-key", http_client=http)
+    try:
+        assert invoke(client) == {"endpoint": name}
+    finally:
+        http.close()
+
+    assert len(seen) == 1
+    request = seen[0]
+    assert request.method == "GET"
+    assert request.url.raw_path.decode().split("?", 1)[0] == expected_path
+    assert {key: request.url.params.get_list(key) for key in request.url.params} == expected_params
+    assert request.headers["X-API-Key"] == "test-key"
+
+
+def test_path_segments_are_percent_encoded():
+    paths = []
+
+    def handler(request):
+        paths.append(request.url.raw_path.decode())
+        return httpx.Response(200, json={})
+
+    http = httpx.Client(base_url="https://example.test/v1", transport=httpx.MockTransport(handler))
+    client = AllowancesClient("key", http_client=http)
+    try:
+        client.dssr.perdiem_by_location("CI", "A/B #1")
+    finally:
+        http.close()
+
+    assert paths == ["/v1/dssr/perdiem/CI/location/A%2FB%20%231"]
+
+
+def test_none_query_values_are_omitted_but_false_and_zero_are_preserved():
+    queries = []
+
+    def handler(request):
+        queries.append(request.url.params)
+        return httpx.Response(200, json={})
+
+    http = httpx.Client(base_url="https://example.test/v1", transport=httpx.MockTransport(handler))
+    client = AllowancesClient("key", http_client=http)
+    try:
+        client.dssr.locations(query=None, offset=0, limit=10)
+    finally:
+        http.close()
+
+    assert dict(queries[0]) == {"offset": "0", "limit": "10"}
+