kuahr 0.3.0__tar.gz

kuahr-0.3.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.DS_Store

kuahr-0.3.0/LICENSE

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

kuahr-0.3.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.5
+Name: kuahr
+Version: 0.3.0
+Summary: Official Python client for Kua company people, payroll drafts, events and webhooks.
+Project-URL: Homepage, https://docs.kuahr.com
+Project-URL: Repository, https://github.com/kuahr/kua-sdk/tree/main/python
+Author: Kua
+License: MIT
+License-File: LICENSE
+Keywords: africa,api,kua,nigeria,payments,payroll,wallet
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kuahr/.github/main/profile/dark.svg">
+  <img src="https://raw.githubusercontent.com/kuahr/.github/main/profile/light.svg" alt="Kua" width="150">
+</picture>
+
+# Kua Python SDK
+
+Official client for Kua company people, payroll drafts, workforce resources,
+events and webhooks. [Documentation](https://docs.kuahr.com/sdks/python).
+
+## Install from public source
+
+Source version 0.3.0 is available here; registry publication is pending. The
+distribution name is `kuahr`, with `import kua`. The unrelated PyPI package
+named `kua` is not this SDK.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+git clone --branch main https://github.com/kuahr/kua-sdk.git
+python -m pip install ./kua-sdk/python
+```
+
+Requires Python 3.9+. On Windows activate `.venv\Scripts\activate` instead.
+Store a sandbox-issued Test key with `payroll:read` in `KUA_API_KEY`:
+
+```python
+import os
+from kua import Kua
+with Kua(api_key=os.environ["KUA_API_KEY"], base_url="https://sandbox-api.kuahr.com") as kua:
+    print(kua.payroll_runs.list())
+```
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest -q
+```
+
+Expected result: an array of this company's Test payroll runs, including `[]`.
+Choose the host explicitly: both clients otherwise default to production.
+
+## Supported boundaries
+
+Employee creation and payroll draft/list operations support Test mode. Events,
+webhooks and workforce add-ons require a separately authorised Live key with the
+matching resource scopes. Draft creation is not approval or payment; salary setup
+is outside this public SDK. Registered-client Kola OIDC uses HTTP separately.
+
+The client does not retry automatically. Persist an operation-specific idempotency
+key and exact request before writes. Credential rotation changes that namespace;
+reconcile uncertain outcomes before retrying under another credential. Webhook
+replay uses a separate stable request key/reason. Queued is not delivered.
+
+## Webhooks and production readiness
+
+Use the included raw-body signature helper and timestamp tolerance, then
+deduplicate the verified body's event ID. Commit durable acceptance before
+acknowledging a delivery. Follow setup, recovery, rotation and go-live guidance at
+https://docs.kuahr.com. Never log credentials or signing secrets.
+
+## Licence
+
+MIT. See LICENSE.

kuahr-0.3.0/README.md

@@ -0,0 +1,65 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kuahr/.github/main/profile/dark.svg">
+  <img src="https://raw.githubusercontent.com/kuahr/.github/main/profile/light.svg" alt="Kua" width="150">
+</picture>
+
+# Kua Python SDK
+
+Official client for Kua company people, payroll drafts, workforce resources,
+events and webhooks. [Documentation](https://docs.kuahr.com/sdks/python).
+
+## Install from public source
+
+Source version 0.3.0 is available here; registry publication is pending. The
+distribution name is `kuahr`, with `import kua`. The unrelated PyPI package
+named `kua` is not this SDK.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+git clone --branch main https://github.com/kuahr/kua-sdk.git
+python -m pip install ./kua-sdk/python
+```
+
+Requires Python 3.9+. On Windows activate `.venv\Scripts\activate` instead.
+Store a sandbox-issued Test key with `payroll:read` in `KUA_API_KEY`:
+
+```python
+import os
+from kua import Kua
+with Kua(api_key=os.environ["KUA_API_KEY"], base_url="https://sandbox-api.kuahr.com") as kua:
+    print(kua.payroll_runs.list())
+```
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest -q
+```
+
+Expected result: an array of this company's Test payroll runs, including `[]`.
+Choose the host explicitly: both clients otherwise default to production.
+
+## Supported boundaries
+
+Employee creation and payroll draft/list operations support Test mode. Events,
+webhooks and workforce add-ons require a separately authorised Live key with the
+matching resource scopes. Draft creation is not approval or payment; salary setup
+is outside this public SDK. Registered-client Kola OIDC uses HTTP separately.
+
+The client does not retry automatically. Persist an operation-specific idempotency
+key and exact request before writes. Credential rotation changes that namespace;
+reconcile uncertain outcomes before retrying under another credential. Webhook
+replay uses a separate stable request key/reason. Queued is not delivered.
+
+## Webhooks and production readiness
+
+Use the included raw-body signature helper and timestamp tolerance, then
+deduplicate the verified body's event ID. Commit durable acceptance before
+acknowledging a delivery. Follow setup, recovery, rotation and go-live guidance at
+https://docs.kuahr.com. Never log credentials or signing secrets.
+
+## Licence
+
+MIT. See LICENSE.

kuahr-0.3.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kuahr"
+version = "0.3.0"
+description = "Official Python client for Kua company people, payroll drafts, events and webhooks."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "Kua" }]
+keywords = ["kua", "payroll", "payments", "wallet", "api", "nigeria", "africa"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Intended Audience :: Developers",
+]
+dependencies = ["httpx>=0.24"]
+
+[project.urls]
+Homepage = "https://docs.kuahr.com"
+Repository = "https://github.com/kuahr/kua-sdk/tree/main/python"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kua"]

kuahr-0.3.0/src/kua/__init__.py

@@ -0,0 +1,67 @@
+"""Official Python client for the Kua API."""
+
+from __future__ import annotations
+
+from .client import Kua
+from .errors import KuaError
+from .models import (
+    Advance,
+    AppraisalCycle,
+    AppraisalReview,
+    CheckIn,
+    EmployeeCreated,
+    EventItem,
+    KeyResult,
+    LeaveAllocation,
+    LeaveBalance,
+    LeaveRequest,
+    LeaveType,
+    Objective,
+    ObjectiveDetail,
+    PayrollRunCreated,
+    PayrollRunSummary,
+    Promotion,
+    TestDataCleared,
+    WebhookCreated,
+    WebhookHistory,
+    WebhookReplayAccepted,
+    WebhookDeliveryAttempt,
+    WebhookReplayRecord,
+    WebhookDeliveryItem,
+    WebhookPingAccepted,
+    WebhookSummary,
+)
+from .webhooks_verify import verify_signature
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "Kua",
+    "KuaError",
+    "verify_signature",
+    "PayrollRunSummary",
+    "PayrollRunCreated",
+    "EventItem",
+    "EmployeeCreated",
+    "TestDataCleared",
+    "WebhookCreated",
+    "WebhookHistory",
+    "WebhookReplayAccepted",
+    "WebhookDeliveryAttempt",
+    "WebhookReplayRecord",
+    "WebhookSummary",
+    "WebhookDeliveryItem",
+    "WebhookPingAccepted",
+    "LeaveType",
+    "LeaveRequest",
+    "LeaveBalance",
+    "LeaveAllocation",
+    "Advance",
+    "Objective",
+    "KeyResult",
+    "CheckIn",
+    "ObjectiveDetail",
+    "AppraisalCycle",
+    "AppraisalReview",
+    "Promotion",
+]

kuahr-0.3.0/src/kua/_http.py

@@ -0,0 +1,80 @@
+"""Internal HTTP transport."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .errors import KuaError
+
+DEFAULT_BASE_URL = "https://api.kuahr.com"
+CLIENT_VERSION = "0.3.0"
+
+
+class _Transport:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        _client: Optional[httpx.Client] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("Kua: `api_key` is required.")
+        self._client = _client or httpx.Client(
+            base_url=(base_url or DEFAULT_BASE_URL).rstrip("/"),
+            timeout=timeout,
+        )
+        # Apply auth/identity headers to the client regardless of whether it was
+        # constructed here or injected (e.g. in tests).
+        self._client.headers.update(
+            {
+                "X-Api-Key": api_key,
+                "Accept": "application/json",
+                "User-Agent": f"kua-python/{CLIENT_VERSION}",
+            }
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Optional[Any] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        headers = {}
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+
+        clean_params = {k: v for k, v in (params or {}).items() if v is not None}
+
+        res = self._client.request(
+            method, path, params=clean_params or None, json=json, headers=headers or None
+        )
+
+        if res.status_code == 204:
+            return None
+
+        data: Any = None
+        if res.content:
+            try:
+                data = res.json()
+            except ValueError:
+                data = None
+
+        if res.status_code >= 400:
+            code = (data or {}).get("code") if isinstance(data, dict) else None
+            message = (data or {}).get("message") if isinstance(data, dict) else None
+            raise KuaError(
+                res.status_code,
+                code or f"HTTP_{res.status_code}",
+                message or f"Kua request failed with status {res.status_code}.",
+            )
+
+        return data
+
+    def close(self) -> None:
+        self._client.close()

kuahr-0.3.0/src/kua/client.py

@@ -0,0 +1,65 @@
+"""The Kua API client."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import httpx
+
+from ._http import _Transport
+from .resources import (
+    Advances,
+    Employees,
+    Events,
+    Leave,
+    PayrollRuns,
+    Performance,
+    TestData,
+    Webhooks,
+)
+
+
+class Kua:
+    """The Kua API client.
+
+    ```python
+    from kua import Kua
+
+    kua = Kua(api_key="kua_live_…")
+    runs = kua.payroll_runs.list()
+    ```
+
+    Can be used as a context manager to close the underlying HTTP connection::
+
+        with Kua(api_key=...) as kua:
+            kua.payroll_runs.list()
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 30.0,
+        _http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        self._transport = _Transport(
+            api_key, base_url=base_url, timeout=timeout, _client=_http_client
+        )
+        self.payroll_runs = PayrollRuns(self._transport)
+        self.employees = Employees(self._transport)
+        self.events = Events(self._transport)
+        self.webhooks = Webhooks(self._transport)
+        self.test_data = TestData(self._transport)
+        self.leave = Leave(self._transport)
+        self.advances = Advances(self._transport)
+        self.performance = Performance(self._transport)
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> "Kua":
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.close()

kuahr-0.3.0/src/kua/errors.py

@@ -0,0 +1,22 @@
+"""Error types for the Kua SDK."""
+
+from __future__ import annotations
+
+
+class KuaError(Exception):
+    """Raised when the Kua API returns a non-2xx response.
+
+    Attributes:
+        code: A stable, machine-readable identifier you can branch on
+            (e.g. ``"INSUFFICIENT_SCOPE"``).
+        status: The HTTP status code.
+    """
+
+    def __init__(self, status: int, code: str, message: str) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message
+
+    def __repr__(self) -> str:  # pragma: no cover - repr convenience
+        return f"KuaError(status={self.status!r}, code={self.code!r}, message={self.message!r})"