pyefris 1.0.0__tar.gz

pyefris-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,41 @@
+name: publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install package with dev deps
+        run: pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check src tests
+      - name: Test
+        run: pytest tests/
+
+  pypi:
+    name: Publish to PyPI
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # OIDC trusted publishing — no API token needed
+      contents: read  # required for actions/checkout (id-token alone strips defaults)
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install build
+        run: pip install build
+      - name: Build sdist and wheel
+        run: python -m build --sdist --wheel
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pyefris-1.0.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+*.db
+*.db-wal
+*.db-shm
+.coverage
+htmlcov/

pyefris-1.0.0/AGENTS.md

@@ -0,0 +1,34 @@
+# pyefris — agent notes
+
+## What this is
+Python client for URA EFRIS S2S API (spec: `docs/Interface+Design+for+EFRIS+v24.0.1URA.md`).
+Greenfield build; no external service access required for dev/test.
+
+## Layout
+- `src/pyefris/constants.py` — endpoints, codes, flags (single source of truth)
+- `src/pyefris/interfaces.py` — 74-code registry w/ per-interface encrypt flags
+- `src/pyefris/crypto/` — AES-ECB, RSA(SHA1withRSA/PKCS1), SessionKeyManager
+- `src/pyefris/envelope.py` — envelope build/parse/decode
+- `src/pyefris/_runner.py` — submit pipeline (record→seal→send→finalize, 402 refresh)
+- `src/pyefris/outbox.py` — relay_pending + RelayWorker
+- `src/pyefris/store/` — Storage protocol, SQLiteStorage (WAL), InMemoryStorage
+- `src/pyefris/models/` — pydantic v2 wire models (alias_generator=to_camel;
+  exceptions use explicit validation/serialization alias pairs)
+- `src/pyefris/services/` — typed service facades; work for sync AND async
+  (methods return whatever runner.submit returns)
+- `src/pyefris/{client,aclient,_client_base}.py` — facades + wiring
+- `tests/` — pytest; StubTransport scripts responses; no network
+
+## Commands
+- Test: `python -m pytest tests/` (pythonpath=src is set in pyproject)
+- Lint: `python -m ruff check src tests`
+- Types: `python -m mypy src/pyefris` (strict)
+
+## Conventions
+- Wire names live in model serialization aliases — constructor kwargs are
+  snake_case; `to_payload()` emits spec names (`mode="json"` → StrDecimal->str).
+- All EFRIS leaf values are strings — use `StrDecimal`, never float for money.
+- New interface: add/adjust `InterfaceSpec` in `interfaces.py`, add models,
+  add a service method. Bare-list responses: set `LIST_FIELD` on the model.
+- Every submission must flow through OperationRunner (audit + idempotency).
+- Never rebuild an envelope on replay — resend the stored one verbatim.

pyefris-1.0.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 1.0.0 (2026-10-27)
+
+Initial release.
+
+- EFRIS v24.0.1 S2S protocol: envelope build/parse, per-interface encryption
+  flags for all 74 registered interface codes.
+- Online crypto: AES-ECB/PKCS7 content, SHA1withRSA request signatures,
+  RSA/PKCS1 T104 session-key unwrap, auto refresh on 401/402.
+- Offline payload mode (base64 content, empty signature).
+- ACID outbox: SQLite WAL store (`synchronous=FULL`), atomic seal+claim+
+  finalize transactions, CAS claims, append-only audit log, unique
+  reference-number idempotency, replayable queue with backoff + worker thread.
+- Typed pydantic v2 models for ~40 core interfaces (session, taxpayer,
+  dictionary, goods, stock, invoicing/credit-notes, batch); generic
+  `client.call()` for the rest.
+- Sync `EfrisClient` + `AsyncEfrisClient` (httpx), `python -m pyefris` CLI,
+  runnable examples.

pyefris-1.0.0/LICENSE

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

pyefris-1.0.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.5
+Name: pyefris
+Version: 1.0.0
+Summary: Python client for URA EFRIS system-to-system e-invoicing integration
+Project-URL: Homepage, https://efris.ura.go.ug/
+Author: pyefris contributors
+License: MIT
+License-File: LICENSE
+Keywords: e-invoicing,efris,fiscal,uganda,ura
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=42
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pyefris
+
+Python client for the **URA EFRIS** (Electronic Fiscal Receipting and Invoicing
+Solution) system-to-system API, per *Interface Design for EFRIS v24.0.1*.
+
+Features:
+
+- Full wire protocol: `{data, globalInfo, returnStateInfo}` envelope, one POST
+  endpoint, `dataDescription` encryption flags per interface.
+- Online-mode crypto exactly as URA requires:
+  `content = base64(AES-ECB/PKCS7(json))`, `signature = base64(SHA1withRSA(content))`,
+  T104 session-key unwrap (RSA/PKCS1), auto-refresh on returnCode `401`/`402`.
+- Offline-mode payload profile (base64 content, empty signature).
+- **ACID outbox**: every submission is recorded atomically in a SQLite
+  (WAL, `synchronous=FULL`) store before it goes on the wire — idempotent
+  retries, crash-safe replay, append-only audit log.
+- Typed pydantic v2 models for the core ~40 interfaces; `client.call(code, ...)`
+  generic escape hatch for the rest of the 74-code registry.
+- Sync `EfrisClient` and `AsyncEfrisClient` (httpx).
+- Python ≥ 3.10. Dependencies: `httpx`, `pydantic>=2`, `cryptography`.
+
+## Install
+
+```bash
+pip install -e .          # local
+pip install -e ".[dev]"   # with test/lint tooling
+```
+
+## Quickstart
+
+```python
+from pyefris import EfrisClient, EfrisConfig
+
+cfg = EfrisConfig(
+    tin="1000029771",
+    device_no="TCS9e0df01728335239",
+    private_key_path="keys/taxpayer_private.pem",  # RSA-2048, registered w/ URA
+    environment="test",                            # or "prod"
+    store_path="pyefris.db",
+)
+
+with EfrisClient(cfg) as client:
+    client.sync_clock()                     # T101: requestTime within ±10min
+    result = client.invoicing.upload_invoice(invoice, reference_no="INV-0001")
+    doc = result.model.exist_invoice_list[0]
+    print(doc.invoice_no, doc.antifake_code, doc.qr_code)
+```
+
+Domain services: `client.session` (T101–T105), `.taxpayer` (T119/T137/T138/T180),
+`.dictionary` (T115/T123–T126/T134/T146), `.goods` (T127/T128/T130/T144),
+`.stock` (T131/T139/T145/T147–T149/T160), `.invoicing`
+(T106–T114/T116–T118/T120–T122/T129). Unmodeled interfaces:
+`client.call("T167", {...})`.
+
+## ACID guarantees
+
+| Property | Mechanism |
+|---|---|
+| **Atomicity** | intent (PENDING) + sealed envelope (SEALED) written in one `BEGIN IMMEDIATE` tx before network I/O; outcome + audit row in a second tx |
+| **Consistency** | `UNIQUE(tin, device_no, interface_code, reference_no)` blocks double-fiscalization; `CHECK` on status enum |
+| **Isolation** | WAL + busy_timeout; claims are compare-and-swap `UPDATE ... WHERE status=?` — threads/processes can't double-send |
+| **Durability** | `synchronous=FULL`; sealed envelope persisted before send; append-only `audit_log` (triggers forbid UPDATE/DELETE) |
+
+Recovery: `client.relay_pending()` re-sends the **byte-identical** stored
+envelope (same `dataExchangeId`, signature) so URA can dedupe. Run it on a
+schedule or `client.start_worker()` for a background thread. Retries use
+exponential backoff (`RetryPolicy`) for transport failures; business
+rejections (`EfrisReturnCodeError`) are terminal by design.
+
+```python
+result = client.invoicing.upload_invoice(inv, reference_no="INV-1")          # raises on dup
+result = client.invoicing.upload_invoice(inv, reference_no="INV-1",
+                                         on_duplicate="return")            # returns stored record
+```
+
+## Config reference
+
+`EfrisConfig(tin, device_no, private_key_pem|_path, environment="test"|"prod",
+mode="online"|"offline", endpoint=..., store_path=..., timeout_seconds=30,
+retry=RetryPolicy(...), server_public_key_pem=...)`. Also `EfrisConfig.from_env()`
+reads `PYEFRIS_*` variables. CLI: `python -m pyefris server-time|login|
+sync-dictionaries|relay|call`.
+
+## Security notes
+
+- SHA1withRSA signatures and AES-ECB are **required by the URA spec**, not a
+  design choice of this package.
+- The decrypted AES session key is cached in the SQLite `kv_state` table —
+  protect the store file with filesystem permissions.
+- `RedactingFilter` (pyefris.logging) scrubs keys/blobs from log records.
+- T102's white-box `clientPriKey`/`keyTable` decryption is AP01-only and not
+  implemented (S2S/AP04 uses your own registered keypair).
+
+## Spec caveats captured in code
+
+- `passowrdDes`, `buyerPlaceOfBusi`, `VehichleNo` keep the spec's spellings.
+- T113/T114/T105/T120/T122 return unencrypted responses even though the
+  request is encrypted.
+- `InvoiceUpload` allows spec additions via `extra="allow"` — unknown fields
+  round-trip instead of being dropped.
+
+## Development
+
+```bash
+python -m pytest tests/          # 50 tests, no network needed
+python -m ruff check src tests
+python -m mypy src/pyefris       # strict mode
+```
+
+See `AGENTS.md` for architecture notes.

pyefris-1.0.0/README.md

@@ -0,0 +1,110 @@
+# pyefris
+
+Python client for the **URA EFRIS** (Electronic Fiscal Receipting and Invoicing
+Solution) system-to-system API, per *Interface Design for EFRIS v24.0.1*.
+
+Features:
+
+- Full wire protocol: `{data, globalInfo, returnStateInfo}` envelope, one POST
+  endpoint, `dataDescription` encryption flags per interface.
+- Online-mode crypto exactly as URA requires:
+  `content = base64(AES-ECB/PKCS7(json))`, `signature = base64(SHA1withRSA(content))`,
+  T104 session-key unwrap (RSA/PKCS1), auto-refresh on returnCode `401`/`402`.
+- Offline-mode payload profile (base64 content, empty signature).
+- **ACID outbox**: every submission is recorded atomically in a SQLite
+  (WAL, `synchronous=FULL`) store before it goes on the wire — idempotent
+  retries, crash-safe replay, append-only audit log.
+- Typed pydantic v2 models for the core ~40 interfaces; `client.call(code, ...)`
+  generic escape hatch for the rest of the 74-code registry.
+- Sync `EfrisClient` and `AsyncEfrisClient` (httpx).
+- Python ≥ 3.10. Dependencies: `httpx`, `pydantic>=2`, `cryptography`.
+
+## Install
+
+```bash
+pip install -e .          # local
+pip install -e ".[dev]"   # with test/lint tooling
+```
+
+## Quickstart
+
+```python
+from pyefris import EfrisClient, EfrisConfig
+
+cfg = EfrisConfig(
+    tin="1000029771",
+    device_no="TCS9e0df01728335239",
+    private_key_path="keys/taxpayer_private.pem",  # RSA-2048, registered w/ URA
+    environment="test",                            # or "prod"
+    store_path="pyefris.db",
+)
+
+with EfrisClient(cfg) as client:
+    client.sync_clock()                     # T101: requestTime within ±10min
+    result = client.invoicing.upload_invoice(invoice, reference_no="INV-0001")
+    doc = result.model.exist_invoice_list[0]
+    print(doc.invoice_no, doc.antifake_code, doc.qr_code)
+```
+
+Domain services: `client.session` (T101–T105), `.taxpayer` (T119/T137/T138/T180),
+`.dictionary` (T115/T123–T126/T134/T146), `.goods` (T127/T128/T130/T144),
+`.stock` (T131/T139/T145/T147–T149/T160), `.invoicing`
+(T106–T114/T116–T118/T120–T122/T129). Unmodeled interfaces:
+`client.call("T167", {...})`.
+
+## ACID guarantees
+
+| Property | Mechanism |
+|---|---|
+| **Atomicity** | intent (PENDING) + sealed envelope (SEALED) written in one `BEGIN IMMEDIATE` tx before network I/O; outcome + audit row in a second tx |
+| **Consistency** | `UNIQUE(tin, device_no, interface_code, reference_no)` blocks double-fiscalization; `CHECK` on status enum |
+| **Isolation** | WAL + busy_timeout; claims are compare-and-swap `UPDATE ... WHERE status=?` — threads/processes can't double-send |
+| **Durability** | `synchronous=FULL`; sealed envelope persisted before send; append-only `audit_log` (triggers forbid UPDATE/DELETE) |
+
+Recovery: `client.relay_pending()` re-sends the **byte-identical** stored
+envelope (same `dataExchangeId`, signature) so URA can dedupe. Run it on a
+schedule or `client.start_worker()` for a background thread. Retries use
+exponential backoff (`RetryPolicy`) for transport failures; business
+rejections (`EfrisReturnCodeError`) are terminal by design.
+
+```python
+result = client.invoicing.upload_invoice(inv, reference_no="INV-1")          # raises on dup
+result = client.invoicing.upload_invoice(inv, reference_no="INV-1",
+                                         on_duplicate="return")            # returns stored record
+```
+
+## Config reference
+
+`EfrisConfig(tin, device_no, private_key_pem|_path, environment="test"|"prod",
+mode="online"|"offline", endpoint=..., store_path=..., timeout_seconds=30,
+retry=RetryPolicy(...), server_public_key_pem=...)`. Also `EfrisConfig.from_env()`
+reads `PYEFRIS_*` variables. CLI: `python -m pyefris server-time|login|
+sync-dictionaries|relay|call`.
+
+## Security notes
+
+- SHA1withRSA signatures and AES-ECB are **required by the URA spec**, not a
+  design choice of this package.
+- The decrypted AES session key is cached in the SQLite `kv_state` table —
+  protect the store file with filesystem permissions.
+- `RedactingFilter` (pyefris.logging) scrubs keys/blobs from log records.
+- T102's white-box `clientPriKey`/`keyTable` decryption is AP01-only and not
+  implemented (S2S/AP04 uses your own registered keypair).
+
+## Spec caveats captured in code
+
+- `passowrdDes`, `buyerPlaceOfBusi`, `VehichleNo` keep the spec's spellings.
+- T113/T114/T105/T120/T122 return unencrypted responses even though the
+  request is encrypted.
+- `InvoiceUpload` allows spec additions via `extra="allow"` — unknown fields
+  round-trip instead of being dropped.
+
+## Development
+
+```bash
+python -m pytest tests/          # 50 tests, no network needed
+python -m ruff check src tests
+python -m mypy src/pyefris       # strict mode
+```
+
+See `AGENTS.md` for architecture notes.