pyefris 1.0.0__py3-none-any.whl

pyefris/__init__.py

@@ -0,0 +1,88 @@
+"""pyefris — URA EFRIS system-to-system integration client.
+
+Quick start::
+
+    from pyefris import EfrisClient, EfrisConfig
+
+    cfg = EfrisConfig(
+        tin="1000029771",
+        device_no="TCS9e0df01728335239",
+        private_key_path="keys/taxpayer_private.pem",
+        environment="test",
+    )
+    with EfrisClient(cfg) as client:
+        client.sync_clock()
+        result = client.invoicing.upload_invoice(invoice, reference_no="INV-001")
+"""
+
+from ._runner import SubmitResult
+from .aclient import AsyncEfrisClient
+from .client import EfrisClient
+from .config import EfrisConfig, RetryPolicy
+from .constants import Environment, Mode
+from .crypto.keys import KeyStore
+from .crypto.rsa import generate_rsa_keypair, private_key_to_pem, public_key_to_pem
+from .errors import (
+    ClockSkewError,
+    CryptoError,
+    DuplicateSubmissionError,
+    EfrisError,
+    EfrisReturnCodeError,
+    EnvelopeError,
+    KeyLoadError,
+    SignatureError,
+    StorageError,
+    TransportError,
+    UnknownInterfaceError,
+    ValidationError,
+)
+from .interfaces import InterfaceSpec, lookup
+from .outbox import RelayWorker
+from .store import (
+    AuditRecord,
+    InMemoryStorage,
+    OutboxRecord,
+    RelaySummary,
+    SQLiteStorage,
+    Storage,
+    UnitOfWork,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "AsyncEfrisClient",
+    "AuditRecord",
+    "ClockSkewError",
+    "CryptoError",
+    "DuplicateSubmissionError",
+    "EfrisClient",
+    "EfrisConfig",
+    "EfrisError",
+    "EfrisReturnCodeError",
+    "EnvelopeError",
+    "Environment",
+    "InMemoryStorage",
+    "InterfaceSpec",
+    "KeyLoadError",
+    "KeyStore",
+    "Mode",
+    "OutboxRecord",
+    "RelaySummary",
+    "RelayWorker",
+    "RetryPolicy",
+    "SQLiteStorage",
+    "SignatureError",
+    "Storage",
+    "StorageError",
+    "SubmitResult",
+    "TransportError",
+    "UnitOfWork",
+    "UnknownInterfaceError",
+    "ValidationError",
+    "__version__",
+    "generate_rsa_keypair",
+    "lookup",
+    "private_key_to_pem",
+    "public_key_to_pem",
+]

pyefris/__main__.py

@@ -0,0 +1,77 @@
+"""Minimal CLI: ``python -m pyefris <command>``.
+
+Commands read config from PYEFRIS_* env vars (see EfrisConfig.from_env).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .client import EfrisClient
+from .config import EfrisConfig
+from .errors import EfrisError
+
+
+def _client(args: argparse.Namespace) -> EfrisClient:
+    cfg = EfrisConfig.from_env()
+    if args.endpoint:
+        cfg = cfg.model_copy(update={"endpoint": args.endpoint})
+    if args.store:
+        cfg = cfg.model_copy(update={"store_path": args.store})
+    return EfrisClient(cfg)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="pyefris")
+    parser.add_argument("--endpoint", help="override API endpoint")
+    parser.add_argument("--store", help="sqlite store path")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    sub.add_parser("server-time", help="T101 server time check")
+    sub.add_parser("login", help="T103 login")
+    sub.add_parser("sync-dictionaries", help="T115 dictionary fetch")
+    relay = sub.add_parser("relay", help="replay pending outbox rows")
+    relay.add_argument("--limit", type=int, default=100)
+    call = sub.add_parser("call", help="generic interface call")
+    call.add_argument("interface_code")
+    call.add_argument("payload", nargs="?", default=None,
+                      help="JSON payload (or @file)")
+
+    args = parser.parse_args(argv)
+
+    try:
+        with _client(args) as client:
+            if args.cmd == "server-time":
+                result = client.session.get_server_time()
+            elif args.cmd == "login":
+                result = client.session.login()
+            elif args.cmd == "sync-dictionaries":
+                print(client.sync_dictionaries())
+                return 0
+            elif args.cmd == "relay":
+                summary = client.relay_pending(limit=args.limit)
+                print(summary)
+                return 0
+            elif args.cmd == "call":
+                payload = args.payload
+                if payload and payload.startswith("@"):
+                    payload = open(payload[1:], encoding="utf-8").read()
+                result = client.call(args.interface_code, payload)
+            else:  # pragma: no cover
+                parser.error(f"unknown command {args.cmd}")
+                return 2
+    except EfrisError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    print(f"returnCode={result.return_code} returnMessage={result.return_message}")
+    if result.content is not None:
+        from .serialization import canonical_dumps
+
+        print(canonical_dumps(result.content))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pyefris/_client_base.py

@@ -0,0 +1,173 @@
+"""Shared wiring for sync/async clients: keys, store, session keys, services."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from ._runner import AsyncOperationRunner, OperationRunner, SubmitResult
+from .clock import MutableClock, OffsetClock, SystemClock, measure_offset, parse_server_time
+from .config import EfrisConfig
+from .crypto.keys import KeyStore
+from .crypto.session import SessionKey, SessionKeyManager, decode_t104
+from .errors import EnvelopeError
+from .outbox import AsyncOutboxProcessor, OutboxProcessor
+from .store.base import Storage
+from .store.sqlite import SQLiteStorage
+from .transport import AsyncHttpxTransport, AsyncTransport, HttpxTransport, SyncTransport
+
+
+def _default_store(config: EfrisConfig) -> Storage:
+    return SQLiteStorage(config.store_path)
+
+
+class _ClientBase:
+    """Common state for EfrisClient and AsyncEfrisClient."""
+
+    def _init_common(
+        self,
+        config: EfrisConfig,
+        store: Storage | None,
+        clock: MutableClock,
+        key_store: KeyStore | None,
+    ) -> None:
+        self.config = config
+        self.store = store or _default_store(config)
+        self.clock = clock
+        self.key_store = key_store or KeyStore.from_config(config)
+
+    def _make_session_manager(
+        self, fetch: Callable[[], SessionKey]
+    ) -> SessionKeyManager:
+        kv_key = f"session_key:{self.config.tin}:{self.config.device_no}"
+        return SessionKeyManager(
+            fetch,
+            persist=lambda k: self.store.set_kv(kv_key, k.to_json()),
+            load_persisted=lambda: (
+                SessionKey.from_json(v) if (v := self.store.get_kv(kv_key)) else None
+            ),
+        )
+
+    def _decode_t104(self, result: SubmitResult) -> SessionKey:
+        content = result.content
+        if not isinstance(content, dict) or "passowrdDes" not in content:
+            raise EnvelopeError("T104 response missing 'passowrdDes'")
+        if self.key_store.private_key is None:
+            raise EnvelopeError("a private key is required to unwrap the session key")
+        return decode_t104(
+            content["passowrdDes"], content.get("sign", ""),
+            self.key_store.private_key,
+        )
+
+    def _apply_server_time(self, result: SubmitResult) -> None:
+        content = result.content
+        if isinstance(content, dict) and content.get("currentTime"):
+            server_now = parse_server_time(content["currentTime"])
+            local_now = self.clock.now()
+            self.clock.inner = OffsetClock(
+                SystemClock(), measure_offset(server_now, local_now)
+            )
+
+
+class EfrisClientCore(_ClientBase):
+    """Wires the synchronous pipeline."""
+
+    def __init__(
+        self,
+        config: EfrisConfig,
+        *,
+        store: Storage | None = None,
+        transport: SyncTransport | None = None,
+        clock: MutableClock | None = None,
+        key_store: KeyStore | None = None,
+    ) -> None:
+        clock = clock or MutableClock()
+        self._init_common(config, store, clock, key_store)
+        self.transport = transport or HttpxTransport()
+        self.session_keys = self._make_session_manager(self._fetch_session_key)
+        self.runner = OperationRunner(
+            config=self.config,
+            key_store=self.key_store,
+            session_keys=self.session_keys,
+            transport=self.transport,
+            store=self.store,
+            clock=self.clock,
+        )
+        self.outbox = OutboxProcessor(self.runner, self.store)
+
+        from .services import (
+            DictionaryService,
+            GoodsService,
+            InvoicingService,
+            SessionService,
+            StockService,
+            TaxpayerService,
+        )
+
+        self.session = SessionService(self.runner)
+        self.taxpayer = TaxpayerService(self.runner)
+        self.dictionary = DictionaryService(self.runner)
+        self.goods = GoodsService(self.runner)
+        self.stock = StockService(self.runner)
+        self.invoicing = InvoicingService(self.runner)
+
+    def _fetch_session_key(self) -> SessionKey:
+        result = self.runner.submit("T104", None, _is_key_refresh=True)
+        return self._decode_t104(result)
+
+
+class AsyncEfrisClientCore(_ClientBase):
+    """Wires the asynchronous pipeline."""
+
+    def __init__(
+        self,
+        config: EfrisConfig,
+        *,
+        store: Storage | None = None,
+        transport: AsyncTransport | None = None,
+        clock: MutableClock | None = None,
+        key_store: KeyStore | None = None,
+    ) -> None:
+        clock = clock or MutableClock()
+        self._init_common(config, store, clock, key_store)
+        self.transport = transport or AsyncHttpxTransport()
+        self.session_keys = self._make_session_manager(self._fetch_session_key_sync)
+        self.runner = AsyncOperationRunner(
+            config=self.config,
+            key_store=self.key_store,
+            session_keys=self.session_keys,
+            transport=self.transport,
+            store=self.store,
+            clock=self.clock,
+        )
+        self.outbox = AsyncOutboxProcessor(self.runner, self.store)
+
+        from .services import (
+            DictionaryService,
+            GoodsService,
+            InvoicingService,
+            SessionService,
+            StockService,
+            TaxpayerService,
+        )
+
+        self.session = SessionService(self.runner)
+        self.taxpayer = TaxpayerService(self.runner)
+        self.dictionary = DictionaryService(self.runner)
+        self.goods = GoodsService(self.runner)
+        self.stock = StockService(self.runner)
+        self.invoicing = InvoicingService(self.runner)
+
+    def _fetch_session_key_sync(self) -> SessionKey:
+        """T104 fetch used by SessionKeyManager (called from worker thread).
+
+        Routes through the sync inner runner of AsyncOperationRunner so the
+        POST executes on the adapter's one-shot event loop.
+        """
+        from .interfaces import lookup
+
+        result = self.runner._sync._submit(
+            lookup("T104"),
+            None, reference_no=None, extend_field_extra=None,
+            on_duplicate="raise", _is_key_refresh=True,
+        )
+        return self._decode_t104(result)