Metadata-Version: 2.5
Name: openepcis-client
Version: 0.1.0
Summary: OpenEPCIS platform client: core transport and auth, master data publication, GS1 key registry
Project-URL: Source, https://github.com/openepcis/openepcis-client-python
Project-URL: Issues, https://github.com/openepcis/openepcis-client-python/issues
Project-URL: Changelog, https://github.com/openepcis/openepcis-client-python/releases
Author: benelog GmbH & Co. KG
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: epcis-event-hash-generator==1.9.3; extra == 'dev'
Requires-Dist: mypy>=1.14; extra == 'dev'
Requires-Dist: pip-licenses>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: reuse>=5; extra == 'dev'
Requires-Dist: ruff==0.16.2; extra == 'dev'
Requires-Dist: types-requests; extra == 'dev'
Provides-Extra: hash
Requires-Dist: epcis-event-hash-generator==1.9.3; extra == 'hash'
Description-Content-Type: text/markdown

<!-- SPDX-License-Identifier: Apache-2.0 -->
<!-- SPDX-FileCopyrightText: 2026 benelog GmbH & Co. KG -->

# openepcis-client-python

Client library for the OpenEPCIS platform. It carries the parts of a
connector that are the same in every host system: transport and authentication,
GS1 identifier arithmetic, master data publication, and the GS1 key registry.
Host adapters (the Odoo addon, the ERPNext app) stay thin and framework
specific; this library holds no host dependency.

| | |
|---|---|
| Licence | Apache-2.0 |
| Python | 3.10 or newer |
| Dependencies | `requests` only |
| Consumers | `openepcis-odoo` (Odoo 18/19), which vendors this package |
| Source | https://github.com/openepcis/openepcis-client-python |

## Modules

```
openepcis_client/
  core/        Identifiers, Digital Link URIs, transport, auth, errors
  masterdata/  Product and organization records, upsert, bulk, GPC
  registry/    GTIN/GLN allocation, credential deposit, Verified by GS1
  events/      EPCIS 2.0 visibility events: building them, capturing them
```

`masterdata/` and `events/` address two different services. Master data goes to
the catalog behind the Digital Link resolver; events go to an EPCIS repository,
on its own host and behind its own permission — capture needs the `capture`
role, and a credential that publishes products perfectly well is refused there.
Build a second `Client` for it rather than reusing the resolver's.

The resolver endpoints this library depends on are recorded in the Odoo
repository as `doc/api-contract.json` — paths, verbs and status codes only —
and its `tools/check-contract.py` compares that file against a running
deployment.

## Installation

```bash
pip install openepcis-client
```

Releases are cut from tags on GitHub and published to PyPI from there; to
track an unreleased commit, install from the repository instead:

```bash
pip install "openepcis-client @ git+https://github.com/openepcis/openepcis-client-python@main"
```

The `hash` extra adds the canonical CBV event hash used as the `eventID` of
every event this library builds; see `pyproject.toml` for why it is an extra
and what it pulls in. The Odoo addon does not install the package at all: it
carries a verbatim copy under `openepcis_connector/vendor/`, so it stays
installable on any Odoo without a Python package beyond what Odoo ships.

## Usage

One configured URL; the Keycloak realm and token endpoint are discovered from
it (RFC 9728). Authentication uses an OIDC offline token, which the host's
`TokenStore` persists — including the rotated replacement Keycloak may answer
with on every exchange.

```python
from openepcis_client.core.auth import InMemoryTokenStore, OfflineTokenAuth
from openepcis_client.core.client import Client
from openepcis_client.core.config import ClientConfig
from openepcis_client.masterdata import Masterdata
from openepcis_client.registry import Registry

config = ClientConfig(base_url="https://id.epcis.cloud")
auth = OfflineTokenAuth(config, InMemoryTokenStore(offline_token), client_id="my-connector")
client = Client(config, auth)

gtin = Registry(client).draw_key("01")
Masterdata(client).upsert_product(gtin, {"productName": {"en": "Chair"}})
Registry(client).confirm_key("01", gtin)
```

A complete round trip, including release on failure and a Verified-by-GS1
check, is in `examples/publish_product.py`.

## Status

All four modules are in use by the Odoo addon and covered by the test suite.
The vocabulary manifest the master data payloads are checked against is pinned
in `masterdata/vocabulary.json`. The version is 0.x: the API is still allowed
to move between minor versions, and a consumer should pin a release rather
than track `main`.

## Development

```bash
pip install -e ".[dev]"
pytest
mypy
ruff format --check . && ruff check .
reuse lint
```

Contributions are accepted under the Developer Certificate of Origin: sign off
your commits with `git commit -s`. There is no CLA.
