pharos-sdk 0.1.0__tar.gz

pharos_sdk-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,73 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
+        os: [ubuntu-latest]
+        include:
+          # ubuntu-latest is 24.04, and setup-python no longer publishes a 3.8
+          # build for it. We still support 3.8 because the ERPs this SDK talks
+          # to are not always on a current runtime, so it is tested on 22.04.
+          - python-version: '3.8'
+            os: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e '.[dev]'
+      - name: Ruff
+        run: ruff check .
+      - name: Mypy
+        run: mypy --no-site-packages pharos_sdk
+      - name: Pytest
+        run: pytest
+
+  publish:
+    needs: test
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Check the tag matches the package version
+        run: |
+          # Anchored to the assignment: an unanchored quoted-string match reads
+          # the module docstring instead, which is what it did the first time
+          # this guard ever ran.
+          version="$(python - <<'PY'
+          import pathlib
+          import re
+
+          text = pathlib.Path("pharos_sdk/version.py").read_text()
+          print(re.search(r'^__version__\s*=\s*"([^"]+)"', text, re.M).group(1))
+          PY
+          )"
+          tag="${GITHUB_REF_NAME#v}"
+          if [ "$version" != "$tag" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match version.py ($version)." >&2
+            exit 1
+          fi
+      - name: Build
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

pharos_sdk-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+/.mypy_cache/
+/.pytest_cache/
+/.ruff_cache/
+/dist/
+/.venv/
+/uv.lock
+*.egg-info/
+__pycache__/
+.coverage
+*.swp

pharos_sdk-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.1.0 - 2026-08-02
+
+- Initial Pharos Connect SDK with sync and async clients.
+- Add dataclass response models and explicit parsers for the OpenAPI contract.
+- Add webhook signature verification and event parsing. An unrecognised event
+  type raises `UnsupportedWebhookEvent`, separate from
+  `WebhookVerificationError`, so a handler can tell a new event apart from a
+  bad delivery and acknowledge it: a rejected delivery counts as a failure, and
+  enough of those suspend the endpoint.
+- Accept a webhook body in either shape the platform delivers: pass the
+  request's `Content-Type` to `verify` and a form-encoded endpoint is read
+  as readily as a JSON one, producing the same event object.
+- Send the API key as `Authorization: Bearer` or, with
+  `auth_scheme="api_key"`, as `X-Pharos-Key`, for callers behind a proxy
+  that claims the `Authorization` header.
+- Ship inline type information (PEP 561).
+- Map every error response to `APIError`, including gateway pages and empty
+  bodies that never reached the API.
+- Address requests absolutely, so a caller-supplied `httpx` client works without
+  repeating the base URL.
+- Identify the SDK with a `User-Agent` of `pharos-sdk/<version>`.

pharos_sdk-0.1.0/LICENSE

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

pharos_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: pharos-sdk
+Version: 0.1.0
+Summary: Official Python SDK for Pharos Connect.
+Project-URL: Homepage, https://pharos.pe/desarrolladores/
+Project-URL: Repository, https://github.com/pharos-pe/pharos-python-sdk
+Project-URL: Changelog, https://github.com/pharos-pe/pharos-python-sdk/blob/main/CHANGELOG.md
+Author-email: Pharos <contacto@pharos.pe>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aduanas,customs,dua,peru,pharos,sunat,webhooks
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.8
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy<1.15,>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov<6,>=5.0; extra == 'dev'
+Requires-Dist: pytest<9,>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pharos-sdk
+
+Official Python SDK for Pharos Connect.
+
+- Documentation: https://pharos.pe/desarrolladores/
+- Repository: https://github.com/pharos-pe/pharos-python-sdk
+
+## Installation
+
+```bash
+pip install pharos-sdk
+```
+
+Supports Python 3.8+.
+
+## API Client
+
+Use the client directly when your application owns a long-lived process.
+
+```python
+import os
+
+from pharos_sdk import PharosClient
+
+client = PharosClient(os.environ["PHAROS_API_KEY"])
+latest = client.declarations.latest(limit=10)
+
+for summary in latest.data:
+    declaration = client.declarations.get(summary.full_number)
+    process_declaration(declaration)
+
+client.close()
+```
+
+Use a context manager when the client is short-lived.
+
+```python
+import os
+
+from pharos_sdk import PharosClient
+
+with PharosClient(os.environ["PHAROS_API_KEY"]) as client:
+    importers = client.importers.list()
+```
+
+### Sending the key in `X-Pharos-Key`
+
+The key travels in `Authorization: Bearer …` by default. Pharos also accepts it
+in `X-Pharos-Key`, which is what to reach for when something between you and the
+API takes the `Authorization` header for itself — a corporate proxy or an API
+gateway that authenticates you to itself and rewrites it on the way out.
+
+```python
+client = PharosClient(os.environ["PHAROS_API_KEY"], auth_scheme="api_key")
+```
+
+Both clients take it, and both accept the `AuthScheme` enum if you would rather
+not pass a string:
+
+```python
+from pharos_sdk import AuthScheme
+
+client = PharosClient(os.environ["PHAROS_API_KEY"], auth_scheme=AuthScheme.API_KEY)
+```
+
+Anything other than `"bearer"` or `"api_key"` raises `ConfigurationError` when
+the client is built, rather than on the first request.
+
+## Async Client
+
+```python
+import os
+
+from pharos_sdk import AsyncPharosClient
+
+client = AsyncPharosClient(os.environ["PHAROS_API_KEY"])
+latest = await client.declarations.latest()
+await client.close()
+```
+
+```python
+import os
+
+from pharos_sdk import AsyncPharosClient
+
+async with AsyncPharosClient(os.environ["PHAROS_API_KEY"]) as client:
+    importers = await client.importers.list()
+```
+
+## Errors
+
+Every SDK exception derives from `PharosError`. Failures that reached the API and
+came back with a status derive from `APIError`, which carries `status_code`, the
+documented `code`, and the response `headers`.
+
+```python
+declaration = client.declarations.get("118-2026-10-001234-00")
+```
+
+Catch `NotFoundError` when a missing declaration is part of your normal workflow.
+Catch `RateLimitError` or `ServerError` at your job boundary if you want to back
+off and retry.
+
+| Exception | Raised when |
+|---|---|
+| `AuthenticationError` | The key is missing or invalid (401) |
+| `AuthorizationError` | Pharos Connect is not enabled for the account, or the source IP is not on the key's allowlist (403) |
+| `NotFoundError` | The resource does not exist **or is outside your scope** (404) |
+| `RateLimitError` | The hourly request limit was exceeded (429). `retry_after` holds the seconds to wait |
+| `InvalidRequestError` | A parameter is not valid (400) |
+| `ServerError` | An unexpected failure on the Pharos side, including gateway errors (5xx) |
+| `TransportError` | The request never got a response — DNS, TLS, connection or timeout |
+| `ResponseDecodeError` | A successful response did not match the published contract |
+
+**The SDK does not retry.** Reads are idempotent, so retrying is safe, but the
+policy is yours: catch `RateLimitError` and `ServerError`, and back off using
+`retry_after` when it is set.
+
+## Declaration Numbers
+
+Declaration methods accept either the full DUA number as a string or a structured
+`DeclarationNumber`.
+
+```python
+from pharos_sdk.models import DeclarationNumber
+
+number = DeclarationNumber(
+    customs_office="118",
+    year=2026,
+    regime="10",
+    number=1234,
+    control_number="00",
+)
+
+declaration = client.declarations.get(number)
+items = client.declarations.items(number)
+```
+
+## Webhooks
+
+```python
+import os
+
+from pharos_sdk.webhooks import WebhookVerifier
+
+verifier = WebhookVerifier(os.environ["PHAROS_WEBHOOK_SECRET"])
+event = verifier.verify(request_body, signature_header)
+handle_event(event)
+```
+
+Pass the body **exactly as it arrived**, before any parsing: the signature covers
+the raw bytes. `verify` checks the signature and the timestamp — five minutes of
+tolerance by default — and raises `WebhookVerificationError` if either fails.
+
+### Form-encoded endpoints
+
+An endpoint can be configured to receive `application/x-www-form-urlencoded`
+instead of JSON. Pass the request's `Content-Type` and the verifier reads either:
+
+```python
+event = verifier.verify(
+    request_body,
+    signature_header,
+    content_type=request.headers["Content-Type"],
+)
+```
+
+Nothing is inferred from the body — Pharos always sends the header, so it is the
+sender's own statement of which shape it used. Omit the argument and the body is
+read as JSON, which is what an endpoint receives unless you asked for the other.
+A `Content-Type` that is neither raises `WebhookVerificationError` rather than
+being read as a guess.
+
+You get the same event object either way. A form carries no types, so Pharos
+sends every value as text and the two objects as text holding JSON; the verifier
+undoes exactly that. The one difference is `event.extra`: any additional field
+configured for your endpoint stays a string, because the form did not carry its
+type either.
+
+An event type newer than your installed SDK raises `UnsupportedWebhookEvent`,
+which is deliberately **not** a `WebhookVerificationError`: the delivery is
+authentic, only its type is unknown. Catch it and answer 2xx, or repeated
+failures will suspend your endpoint.
+
+```python
+event = verifier.verify(request_body, signature_header)
+handle_event(event)
+return http_200()
+```
+
+At your webhook boundary, answer `2xx` for `UnsupportedWebhookEvent` only when
+your system deliberately ignores event types unknown to this SDK version.
+
+Deduplicate on `event.event_id`. It is the same across retries **and** across
+every endpoint subscribed to the same fact, which the delivery id is not.
+
+Anything Pharos was asked to add to your notifications — a tenant identifier, a
+routing key — arrives in `event.extra`, keyed as you configured it. The
+documented fields are attributes; `extra` is everything else.
+
+## Development
+
+```bash
+uv run pytest
+uv run ruff check .
+uv run mypy --no-site-packages pharos_sdk
+```
+
+`pytest` prints coverage by default.

pharos_sdk-0.1.0/README.md

@@ -0,0 +1,209 @@
+# pharos-sdk
+
+Official Python SDK for Pharos Connect.
+
+- Documentation: https://pharos.pe/desarrolladores/
+- Repository: https://github.com/pharos-pe/pharos-python-sdk
+
+## Installation
+
+```bash
+pip install pharos-sdk
+```
+
+Supports Python 3.8+.
+
+## API Client
+
+Use the client directly when your application owns a long-lived process.
+
+```python
+import os
+
+from pharos_sdk import PharosClient
+
+client = PharosClient(os.environ["PHAROS_API_KEY"])
+latest = client.declarations.latest(limit=10)
+
+for summary in latest.data:
+    declaration = client.declarations.get(summary.full_number)
+    process_declaration(declaration)
+
+client.close()
+```
+
+Use a context manager when the client is short-lived.
+
+```python
+import os
+
+from pharos_sdk import PharosClient
+
+with PharosClient(os.environ["PHAROS_API_KEY"]) as client:
+    importers = client.importers.list()
+```
+
+### Sending the key in `X-Pharos-Key`
+
+The key travels in `Authorization: Bearer …` by default. Pharos also accepts it
+in `X-Pharos-Key`, which is what to reach for when something between you and the
+API takes the `Authorization` header for itself — a corporate proxy or an API
+gateway that authenticates you to itself and rewrites it on the way out.
+
+```python
+client = PharosClient(os.environ["PHAROS_API_KEY"], auth_scheme="api_key")
+```
+
+Both clients take it, and both accept the `AuthScheme` enum if you would rather
+not pass a string:
+
+```python
+from pharos_sdk import AuthScheme
+
+client = PharosClient(os.environ["PHAROS_API_KEY"], auth_scheme=AuthScheme.API_KEY)
+```
+
+Anything other than `"bearer"` or `"api_key"` raises `ConfigurationError` when
+the client is built, rather than on the first request.
+
+## Async Client
+
+```python
+import os
+
+from pharos_sdk import AsyncPharosClient
+
+client = AsyncPharosClient(os.environ["PHAROS_API_KEY"])
+latest = await client.declarations.latest()
+await client.close()
+```
+
+```python
+import os
+
+from pharos_sdk import AsyncPharosClient
+
+async with AsyncPharosClient(os.environ["PHAROS_API_KEY"]) as client:
+    importers = await client.importers.list()
+```
+
+## Errors
+
+Every SDK exception derives from `PharosError`. Failures that reached the API and
+came back with a status derive from `APIError`, which carries `status_code`, the
+documented `code`, and the response `headers`.
+
+```python
+declaration = client.declarations.get("118-2026-10-001234-00")
+```
+
+Catch `NotFoundError` when a missing declaration is part of your normal workflow.
+Catch `RateLimitError` or `ServerError` at your job boundary if you want to back
+off and retry.
+
+| Exception | Raised when |
+|---|---|
+| `AuthenticationError` | The key is missing or invalid (401) |
+| `AuthorizationError` | Pharos Connect is not enabled for the account, or the source IP is not on the key's allowlist (403) |
+| `NotFoundError` | The resource does not exist **or is outside your scope** (404) |
+| `RateLimitError` | The hourly request limit was exceeded (429). `retry_after` holds the seconds to wait |
+| `InvalidRequestError` | A parameter is not valid (400) |
+| `ServerError` | An unexpected failure on the Pharos side, including gateway errors (5xx) |
+| `TransportError` | The request never got a response — DNS, TLS, connection or timeout |
+| `ResponseDecodeError` | A successful response did not match the published contract |
+
+**The SDK does not retry.** Reads are idempotent, so retrying is safe, but the
+policy is yours: catch `RateLimitError` and `ServerError`, and back off using
+`retry_after` when it is set.
+
+## Declaration Numbers
+
+Declaration methods accept either the full DUA number as a string or a structured
+`DeclarationNumber`.
+
+```python
+from pharos_sdk.models import DeclarationNumber
+
+number = DeclarationNumber(
+    customs_office="118",
+    year=2026,
+    regime="10",
+    number=1234,
+    control_number="00",
+)
+
+declaration = client.declarations.get(number)
+items = client.declarations.items(number)
+```
+
+## Webhooks
+
+```python
+import os
+
+from pharos_sdk.webhooks import WebhookVerifier
+
+verifier = WebhookVerifier(os.environ["PHAROS_WEBHOOK_SECRET"])
+event = verifier.verify(request_body, signature_header)
+handle_event(event)
+```
+
+Pass the body **exactly as it arrived**, before any parsing: the signature covers
+the raw bytes. `verify` checks the signature and the timestamp — five minutes of
+tolerance by default — and raises `WebhookVerificationError` if either fails.
+
+### Form-encoded endpoints
+
+An endpoint can be configured to receive `application/x-www-form-urlencoded`
+instead of JSON. Pass the request's `Content-Type` and the verifier reads either:
+
+```python
+event = verifier.verify(
+    request_body,
+    signature_header,
+    content_type=request.headers["Content-Type"],
+)
+```
+
+Nothing is inferred from the body — Pharos always sends the header, so it is the
+sender's own statement of which shape it used. Omit the argument and the body is
+read as JSON, which is what an endpoint receives unless you asked for the other.
+A `Content-Type` that is neither raises `WebhookVerificationError` rather than
+being read as a guess.
+
+You get the same event object either way. A form carries no types, so Pharos
+sends every value as text and the two objects as text holding JSON; the verifier
+undoes exactly that. The one difference is `event.extra`: any additional field
+configured for your endpoint stays a string, because the form did not carry its
+type either.
+
+An event type newer than your installed SDK raises `UnsupportedWebhookEvent`,
+which is deliberately **not** a `WebhookVerificationError`: the delivery is
+authentic, only its type is unknown. Catch it and answer 2xx, or repeated
+failures will suspend your endpoint.
+
+```python
+event = verifier.verify(request_body, signature_header)
+handle_event(event)
+return http_200()
+```
+
+At your webhook boundary, answer `2xx` for `UnsupportedWebhookEvent` only when
+your system deliberately ignores event types unknown to this SDK version.
+
+Deduplicate on `event.event_id`. It is the same across retries **and** across
+every endpoint subscribed to the same fact, which the delivery id is not.
+
+Anything Pharos was asked to add to your notifications — a tenant identifier, a
+routing key — arrives in `event.extra`, keyed as you configured it. The
+documented fields are attributes; `extra` is everything else.
+
+## Development
+
+```bash
+uv run pytest
+uv run ruff check .
+uv run mypy --no-site-packages pharos_sdk
+```
+
+`pytest` prints coverage by default.

pharos_sdk-0.1.0/docs/release.md

@@ -0,0 +1,8 @@
+# Release Process
+
+The SDK follows Semantic Versioning independently from the `/api/v1` API version.
+
+1. Update `CHANGELOG.md`.
+2. Run `ruff check .`, `mypy --no-site-packages pharos_sdk`, and `pytest`.
+3. Create an immutable signed tag such as `v0.1.0`.
+4. Push the tag. GitHub Actions publishes to PyPI through Trusted Publishing.

pharos_sdk-0.1.0/examples/async_usage.py

@@ -0,0 +1,26 @@
+import asyncio
+
+from pharos_sdk import AsyncPharosClient
+
+
+async def with_context_manager() -> None:
+    async with AsyncPharosClient("phk_live_...") as client:
+        importers = await client.importers.list()
+        latest = await client.declarations.latest(limit=10)
+        print(importers.count, latest.count)
+
+
+async def without_context_manager() -> None:
+    client = AsyncPharosClient("phk_live_...")
+    importers = await client.importers.list()
+    latest = await client.declarations.latest(limit=10)
+    print(importers.count, latest.count)
+    await client.close()
+
+
+async def main() -> None:
+    await with_context_manager()
+    await without_context_manager()
+
+
+asyncio.run(main())

pharos_sdk-0.1.0/examples/sync_usage.py

@@ -0,0 +1,20 @@
+from pharos_sdk import PharosClient
+
+
+def with_context_manager() -> None:
+    with PharosClient("phk_live_...") as client:
+        importers = client.importers.list()
+        latest = client.declarations.latest(limit=10)
+        print(importers.count, latest.count)
+
+
+def without_context_manager() -> None:
+    client = PharosClient("phk_live_...")
+    importers = client.importers.list()
+    latest = client.declarations.latest(limit=10)
+    print(importers.count, latest.count)
+    client.close()
+
+
+with_context_manager()
+without_context_manager()

pharos_sdk-0.1.0/pharos_sdk/__init__.py

@@ -0,0 +1,8 @@
+"""Official Python SDK for Pharos Connect."""
+
+from pharos_sdk.async_client import AsyncPharosClient
+from pharos_sdk.client import PharosClient
+from pharos_sdk.config import AuthScheme
+from pharos_sdk.version import __version__
+
+__all__ = ["AsyncPharosClient", "AuthScheme", "PharosClient", "__version__"]

pharos_sdk-0.1.0/pharos_sdk/async_client.py

@@ -0,0 +1,52 @@
+"""Asynchronous Pharos Connect client."""
+
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+import httpx
+
+from pharos_sdk.base import BaseClient
+from pharos_sdk.config import BASE_URL, AuthScheme, AuthSchemeInput, make_config
+from pharos_sdk.resources import AsyncDeclarationsResource, AsyncImportersResource
+from pharos_sdk.transport import AsyncTransport
+
+
+class AsyncPharosClient(BaseClient):
+    """Asynchronous client for the Pharos Connect API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = BASE_URL,
+        timeout: float = 10.0,
+        headers: Optional[Dict[str, str]] = None,
+        auth_scheme: AuthSchemeInput = AuthScheme.BEARER,
+        http_client: Optional[httpx.AsyncClient] = None,
+    ) -> None:
+        """Create an asynchronous Pharos Connect client."""
+        config = make_config(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+            headers=headers,
+            auth_scheme=auth_scheme,
+        )
+        self.transport = AsyncTransport(config, http_client=http_client)
+        self.importers = AsyncImportersResource(self.transport)
+        self.declarations = AsyncDeclarationsResource(self.transport)
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client if this SDK instance owns it."""
+        await self.transport.close()
+
+    def is_closed(self) -> bool:
+        """Return whether the underlying HTTP client is closed."""
+        return bool(self.transport.client.is_closed)
+
+    async def __aenter__(self) -> AsyncPharosClient:
+        return self
+
+    async def __aexit__(self, exc_type: object, exc: object, traceback: object) -> None:
+        await self.close()