Metadata-Version: 2.4
Name: qtx-nav-core
Version: 0.2.2
Summary: Python NAV core client port skeleton
Author: Internal
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Requires-Dist: lxml>=5.2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"

# qtx-nav-core

Python package for the NAV Online Szamla core client.

Install/package name: `qtx-nav-core`

Python import package: `qtx_nav_core`

## Quick Start Map

If you open this package months later, start with this mental model:

- `NavAuth`: technical user credentials for NAV signing and authentication
- `NavSoftwareInfo`: software metadata block included in each request
- `NavRequestContext`: immutable container that carries auth, software info, and request ID prefix
- `NavRequestBody`: abstract extension point for a concrete NAV operation
- `NavXmlRequestBuilder`: creates the full NAV XML document from context plus request body
- `NavApiClient`: low-level HTTP client for XML and multipart requests
- `NavCallSpec`: one request execution description, including path and optional file upload settings
- `NavRequestRunner`: high-level orchestrator that builds XML, sends the request, and validates NAV result status
- `NavDocumentStatus`: parsed summary of NAV's `<result>` block
- `NavApiKind` / `NAV_XML_PROFILES`: NAV API profile selection for OSA/eVAT namespaces and request versions
- `NavUtils`: shared helper methods for hashing, decoding, status parsing, and response formatting

## Typical Usage Flow

1. Create a `NavAuth` instance.
2. Create a `NavSoftwareInfo` instance for the calling application.
3. Create a `NavRequestContext` from the auth object and software info.
4. Implement a concrete `NavRequestBody` subclass for the target NAV endpoint.
5. Create a `NavApiClient` with the NAV base URL.
6. Create a `NavRequestRunner` with the API client and request context.
7. Execute the call with `NavCallSpec`.
8. Read the returned XML or let `NavValidationError` surface NAV-side failures.

## API Kind Detection

`NavApiClient.api_kind` is derived from the configured base URL. URLs containing `.eafa.` use `NavApiKind.EVAT`; URLs containing `.onlineszamla.` use `NavApiKind.OSA`. `NavRequestRunner` passes this value to `NavXmlRequestBuilder`, which then selects the matching XML namespaces and request version from `NAV_XML_PROFILES`.

## Software Info

`NavSoftwareInfo` is required for every request. Create and pass a populated instance into `NavRequestContext`; otherwise XML generation raises `ValueError` before the NAV call is sent.

The current model defaults are empty development placeholders only. Real callers must set the software identifier, name, version, developer contact, developer country code, and developer tax number explicitly.

```python
software = NavSoftwareInfo(
    software_id="MOCK-EVAT-12345678",
    software_name="Mock eVAT Client",
    software_operation="LOCAL_SOFTWARE",
    software_main_version="1.0",
    software_dev_name="Mock Developer",
    software_dev_contact="mock.dev@example.com",
    software_dev_country_code="HU",
    software_dev_tax_number="12345678",
)

context = NavRequestContext(auth=auth, software=software)
```

## Package Reference

For a longer in-package reminder that is shipped with the installed distribution, see `qtx_nav_core/docs/package_map.md`.

## Scope

This package currently contains:

- package layout matching the Dart core library
- minimal public exports
- placeholder modules for models, services, and utils
- test directory and tooling configuration

## Package layout

```text
qtx_nav_core/
  models/
  services/
  utils/
tests/
```

## Development

```bash
pip install -e .[dev]
pytest
ruff check .
```

