py-dgii-ecf 0.2.1__tar.gz

py_dgii_ecf-0.2.1/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Secrets — never commit keys, certs, or credentials
+*.p12
+*.pfx
+*.pem
+*.key
+*.crt
+.env
+.env.*

py_dgii_ecf-0.2.1/.python-version

@@ -0,0 +1 @@
+3.12

py_dgii_ecf-0.2.1/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [0.2.1](https://github.com/deuriib/dgii-ecf/compare/python-v0.2.0...python-v0.2.1) (2026-11-02)
+
+
+### Bug Fixes
+
+* **python:** surface authentication failures in the status CLI command ([4005634](https://github.com/deuriib/dgii-ecf/commit/400563462d14d965a521c2275fc8707d24801a3a))
+* surface CLI auth failures and fix release dispatch ([779d0e7](https://github.com/deuriib/dgii-ecf/commit/779d0e7cc0b4e0ec9ffc69d3410990d930734e80))
+
+## [0.2.0](https://github.com/deuriib/dgii-ecf/compare/python-v0.1.0...python-v0.2.0) (2026-11-02)
+
+
+### Features
+
+* **python:** add py-dgii-ecf SDK ([3a4796b](https://github.com/deuriib/dgii-ecf/commit/3a4796b9471f2999a109cc3f69fb464b71804161))
+* scaffold dgii-ecf monorepo with TypeScript and Python SDKs ([41ce340](https://github.com/deuriib/dgii-ecf/commit/41ce34089949c1d38e70fe95d2aa281fa8b8fe87))

py_dgii_ecf-0.2.1/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.5
+Name: py-dgii-ecf
+Version: 0.2.1
+Summary: DGII e-CF electronic invoicing SDK for the Dominican Republic — authenticate, sign (XMLDSig/C14N) and transmit electronic tax documents.
+Author: Deuri Vasquez
+License: MIT
+Keywords: dgii,ecf,electronica,facturacion,invoice,ncf,republica-dominicana,xml
+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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=43.0
+Requires-Dist: httpx2<3,>=2.13
+Requires-Dist: lxml>=5.0
+Requires-Dist: pybreaker>=1.0
+Requires-Dist: result<1,>=0.17
+Requires-Dist: tenacity>=9.0
+Requires-Dist: typer>=0.15
+Description-Content-Type: text/markdown
+
+# py-dgii-ecf
+
+> DGII e-CF electronic invoicing SDK for the Dominican Republic (Python).
+
+Result-pattern (`result`), resilient HTTP (`httpx2` + `tenacity` + `pybreaker`),
+and XMLDSig signing (`lxml` + `cryptography`). No hidden exceptions — every
+fallible call returns a `Result`.
+
+## Install
+
+```bash
+uv add py-dgii-ecf
+# or
+pip install py-dgii-ecf
+```
+
+> Server-side only. Never load in a context that exposes private keys.
+
+## Quick start
+
+```python
+from py_dgii_ecf import ECF, Environment, P12Reader, Signature
+
+reader = P12Reader(password)
+credentials = reader.get_key_from_file("/secure/identity.p12")
+if credentials.is_err():
+    raise SystemExit(credentials.unwrap_err())
+
+ecf = ECF(credentials.unwrap(), Environment.CERT)
+auth = ecf.authenticate()
+if auth.is_err():
+    raise SystemExit(auth.unwrap_err())
+
+signature = Signature(credentials.unwrap().key, credentials.unwrap().cert)
+signed = signature.sign_xml(xml)
+if signed.is_err():
+    raise SystemExit(signed.unwrap_err())
+
+response = ecf.send_electronic_document(signed.unwrap(), "101672919E3100000001.xml")
+response.map(lambda invoice: print(invoice.get("trackId"))).map_err(
+    lambda error: print(error.code, error)
+)
+```
+
+## Result pattern
+
+```python
+result = ecf.status_track_id("some-track-id")
+if result.is_ok():
+    print(result.unwrap().get("estado"))
+else:
+    error = result.unwrap_err()
+    print(error.code, error.message)
+```
+
+## Resilience & idempotency
+
+- Transient failures (network, timeout, 408/429/5xx) are retried with
+  exponential backoff and guarded by a `pybreaker` circuit breaker.
+- `send_electronic_document` / `send_summary` are keyed by
+  `RNC + eNCF + SHA-256(signed XML)`. Provide a persistent `IdempotencyStore`
+  in production.
+
+```python
+ecf = ECF(credentials, Environment.PROD, idempotency_store=my_redis_store)
+```
+
+## CLI
+
+```bash
+py-dgii-ecf sign invoice.xml --p12 identity.p12 --output signed.xml
+py-dgii-ecf authenticate --p12 identity.p12 --environment CertEcf
+py-dgii-ecf status <track-id> --p12 identity.p12
+```
+
+## Modules
+
+`environment`, `types`, `errors`, `result`, `resilience`, `http`, `certificate`,
+`signing`, `transformer`, `utils`, `client`, `cli`.
+
+## License
+
+MIT © 2026 Deuri Vasquez

py_dgii_ecf-0.2.1/README.md

@@ -0,0 +1,83 @@
+# py-dgii-ecf
+
+> DGII e-CF electronic invoicing SDK for the Dominican Republic (Python).
+
+Result-pattern (`result`), resilient HTTP (`httpx2` + `tenacity` + `pybreaker`),
+and XMLDSig signing (`lxml` + `cryptography`). No hidden exceptions — every
+fallible call returns a `Result`.
+
+## Install
+
+```bash
+uv add py-dgii-ecf
+# or
+pip install py-dgii-ecf
+```
+
+> Server-side only. Never load in a context that exposes private keys.
+
+## Quick start
+
+```python
+from py_dgii_ecf import ECF, Environment, P12Reader, Signature
+
+reader = P12Reader(password)
+credentials = reader.get_key_from_file("/secure/identity.p12")
+if credentials.is_err():
+    raise SystemExit(credentials.unwrap_err())
+
+ecf = ECF(credentials.unwrap(), Environment.CERT)
+auth = ecf.authenticate()
+if auth.is_err():
+    raise SystemExit(auth.unwrap_err())
+
+signature = Signature(credentials.unwrap().key, credentials.unwrap().cert)
+signed = signature.sign_xml(xml)
+if signed.is_err():
+    raise SystemExit(signed.unwrap_err())
+
+response = ecf.send_electronic_document(signed.unwrap(), "101672919E3100000001.xml")
+response.map(lambda invoice: print(invoice.get("trackId"))).map_err(
+    lambda error: print(error.code, error)
+)
+```
+
+## Result pattern
+
+```python
+result = ecf.status_track_id("some-track-id")
+if result.is_ok():
+    print(result.unwrap().get("estado"))
+else:
+    error = result.unwrap_err()
+    print(error.code, error.message)
+```
+
+## Resilience & idempotency
+
+- Transient failures (network, timeout, 408/429/5xx) are retried with
+  exponential backoff and guarded by a `pybreaker` circuit breaker.
+- `send_electronic_document` / `send_summary` are keyed by
+  `RNC + eNCF + SHA-256(signed XML)`. Provide a persistent `IdempotencyStore`
+  in production.
+
+```python
+ecf = ECF(credentials, Environment.PROD, idempotency_store=my_redis_store)
+```
+
+## CLI
+
+```bash
+py-dgii-ecf sign invoice.xml --p12 identity.p12 --output signed.xml
+py-dgii-ecf authenticate --p12 identity.p12 --environment CertEcf
+py-dgii-ecf status <track-id> --p12 identity.p12
+```
+
+## Modules
+
+`environment`, `types`, `errors`, `result`, `resilience`, `http`, `certificate`,
+`signing`, `transformer`, `utils`, `client`, `cli`.
+
+## License
+
+MIT © 2026 Deuri Vasquez

py_dgii_ecf-0.2.1/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "py-dgii-ecf"
+version = "0.2.1"
+description = "DGII e-CF electronic invoicing SDK for the Dominican Republic — authenticate, sign (XMLDSig/C14N) and transmit electronic tax documents."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Deuri Vasquez" }]
+keywords = [
+  "dgii",
+  "ecf",
+  "facturacion",
+  "electronica",
+  "republica-dominicana",
+  "invoice",
+  "ncf",
+  "xml",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+  "Topic :: Office/Business :: Financial :: Accounting",
+]
+dependencies = [
+  "httpx2>=2.13,<3",
+  "tenacity>=9.0",
+  "pybreaker>=1.0",
+  "result>=0.17,<1",
+  "lxml>=5.0",
+  "cryptography>=43.0",
+  "typer>=0.15",
+]
+
+[dependency-groups]
+dev = [
+  "ruff>=0.9",
+  "mypy>=1.13",
+  "pytest>=8.3",
+  "pytest-cov>=6.0",
+]
+
+[project.scripts]
+py-dgii-ecf = "py_dgii_ecf.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/py_dgii_ecf"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM", "RUF", "C4", "PTH", "PLC", "PLE"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["py_dgii_ecf"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unused_ignores = true
+disallow_any_explicit = true
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = ["pybreaker.*", "lxml.*", "result.*", "tenacity.*"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.coverage.run]
+source = ["py_dgii_ecf"]

py_dgii_ecf-0.2.1/src/py_dgii_ecf/__init__.py

@@ -0,0 +1,104 @@
+"""DGII e-CF electronic invoicing SDK for the Dominican Republic.
+
+Result-pattern (``result``), resilient HTTP (``httpx2`` + ``tenacity`` +
+``pybreaker``), and XMLDSig signing (``lxml`` + ``cryptography``).
+"""
+
+from __future__ import annotations
+
+from ._json import JsonObject, JsonValue
+from .certificate import CertificateInfo, P12Reader, P12ReaderData
+from .client import ECF
+from .environment import (
+    BaseUrl,
+    Endpoint,
+    Environment,
+    SenderReceiverEndpoint,
+    build_sender_receiver_url,
+    build_url,
+)
+from .errors import (
+    DgiiError,
+    DgiiErrorCode,
+    DgiiErrorContext,
+    extract_dgii_error_message,
+    is_retryable_status,
+    to_dgii_error,
+)
+from .http import (
+    HttpClient,
+    HttpClientOptions,
+    IdempotencyStore,
+    InMemoryIdempotencyStore,
+)
+from .resilience import ResilienceOptions, ResiliencePolicy, is_retryable_error
+from .result import DgiiResult, Err, Ok, Result
+from .signing import Signature, XmlCertificateValidation, validate_xml_certificate
+from .transformer import Transformer
+from .types import (
+    AuthToken,
+    Mensaje,
+    Operation,
+    StatusOperation,
+    TrackStatus,
+)
+from .utils import (
+    convert_ecf32_to_rfce,
+    generate_ecf_qr_code_url,
+    generate_fc_qr_code_url,
+    get_code_six_digit_from_signature,
+    get_current_formatted_date,
+    get_current_formatted_datetime,
+    get_xml_from_body_response,
+)
+
+__version__ = "0.2.1"
+
+__all__ = [
+    "ECF",
+    "AuthToken",
+    "BaseUrl",
+    "CertificateInfo",
+    "DgiiError",
+    "DgiiErrorCode",
+    "DgiiErrorContext",
+    "DgiiResult",
+    "Endpoint",
+    "Environment",
+    "Err",
+    "HttpClient",
+    "HttpClientOptions",
+    "IdempotencyStore",
+    "InMemoryIdempotencyStore",
+    "JsonObject",
+    "JsonValue",
+    "Mensaje",
+    "Ok",
+    "Operation",
+    "P12Reader",
+    "P12ReaderData",
+    "ResilienceOptions",
+    "ResiliencePolicy",
+    "Result",
+    "SenderReceiverEndpoint",
+    "Signature",
+    "StatusOperation",
+    "TrackStatus",
+    "Transformer",
+    "XmlCertificateValidation",
+    "__version__",
+    "build_sender_receiver_url",
+    "build_url",
+    "convert_ecf32_to_rfce",
+    "extract_dgii_error_message",
+    "generate_ecf_qr_code_url",
+    "generate_fc_qr_code_url",
+    "get_code_six_digit_from_signature",
+    "get_current_formatted_date",
+    "get_current_formatted_datetime",
+    "get_xml_from_body_response",
+    "is_retryable_error",
+    "is_retryable_status",
+    "to_dgii_error",
+    "validate_xml_certificate",
+]

py_dgii_ecf-0.2.1/src/py_dgii_ecf/_json.py

@@ -0,0 +1,13 @@
+"""Typing helpers shared across the SDK."""
+
+from __future__ import annotations
+
+from typing import TypeAlias
+
+#: A JSON value as returned by the DGII web services.
+JsonValue: TypeAlias = (
+    str | int | float | bool | list["JsonValue"] | dict[str, "JsonValue"] | None
+)
+
+#: A JSON object as returned by the DGII web services.
+JsonObject: TypeAlias = dict[str, JsonValue]

py_dgii_ecf-0.2.1/src/py_dgii_ecf/certificate.py

@@ -0,0 +1,172 @@
+"""PKCS#12 (.p12) certificate reader."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+
+from cryptography import x509
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.types import PrivateKeyTypes
+from cryptography.hazmat.primitives.serialization import pkcs12
+
+from .errors import DgiiError, DgiiErrorCode
+from .result import DgiiResult, Err, Ok
+
+
+@dataclass(frozen=True, slots=True)
+class P12ReaderData:
+    """PEM-encoded private key, certificate and public key."""
+
+    key: str | None = None
+    cert: str | None = None
+    public_key: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class CertificateInfo:
+    """Basic metadata about an X.509 certificate."""
+
+    subject: str
+    issuer: str
+    valid_from: datetime
+    valid_to: datetime
+    serial_number: str
+
+
+class P12Reader:
+    """Read a PKCS#12 bundle and extract the private key + certificate."""
+
+    def __init__(self, passphrase: str) -> None:
+        self._passphrase = passphrase
+
+    def _load(self, data: bytes) -> tuple[PrivateKeyTypes, x509.Certificate]:
+        password = self._passphrase.encode("utf-8") if self._passphrase else None
+        key, certificate, _ = pkcs12.load_key_and_certificates(data, password)
+        if key is None or certificate is None:
+            raise ValueError("PKCS#12 must contain a private key and certificate")
+        return key, certificate
+
+    def get_key_from_file(self, file_name: str | Path) -> DgiiResult[P12ReaderData]:
+        """Read a .p12 file from disk."""
+        try:
+            return self.get_key_from_bytes(Path(file_name).read_bytes())
+        except OSError as exc:
+            return Err(
+                DgiiError(
+                    f"Unable to read .p12 file: {file_name}",
+                    code=DgiiErrorCode.CERTIFICATE,
+                    cause=exc,
+                )
+            )
+
+    def get_key_from_base64(self, base64_data: str) -> DgiiResult[P12ReaderData]:
+        """Read a base64-encoded .p12 payload."""
+        try:
+            decoded = base64.b64decode(base64_data)
+        except (ValueError, binascii.Error) as exc:
+            return Err(
+                DgiiError(
+                    f"Invalid base64 .p12 payload: {exc}",
+                    code=DgiiErrorCode.CERTIFICATE,
+                    cause=exc,
+                )
+            )
+        return self.get_key_from_bytes(decoded)
+
+    def get_key_from_bytes(self, data: bytes) -> DgiiResult[P12ReaderData]:
+        """Read a raw PKCS#12 byte string."""
+        try:
+            key, certificate = self._load(data)
+            key_pem = key.private_bytes(
+                serialization.Encoding.PEM,
+                serialization.PrivateFormat.PKCS8,
+                serialization.NoEncryption(),
+            ).decode("utf-8")
+            cert_pem = certificate.public_bytes(serialization.Encoding.PEM).decode(
+                "utf-8"
+            )
+            public_key_pem = (
+                key.public_key()
+                .public_bytes(
+                    serialization.Encoding.PEM,
+                    serialization.PublicFormat.SubjectPublicKeyInfo,
+                )
+                .decode("utf-8")
+            )
+            return Ok(
+                P12ReaderData(
+                    key=key_pem,
+                    cert=cert_pem,
+                    public_key=public_key_pem,
+                )
+            )
+        except ValueError as exc:
+            return Err(
+                DgiiError(
+                    f"Unable to parse .p12: {exc}",
+                    code=DgiiErrorCode.CERTIFICATE,
+                    cause=exc,
+                )
+            )
+
+    def get_certificate_info(
+        self,
+        file_name: str | Path,
+    ) -> DgiiResult[CertificateInfo]:
+        """Read certificate metadata from a .p12 file."""
+        try:
+            return self.get_certificate_info_from_bytes(Path(file_name).read_bytes())
+        except OSError as exc:
+            return Err(
+                DgiiError(
+                    f"Unable to read .p12 file: {file_name}",
+                    code=DgiiErrorCode.CERTIFICATE,
+                    cause=exc,
+                )
+            )
+
+    def get_certificate_info_from_base64(
+        self,
+        base64_data: str,
+    ) -> DgiiResult[CertificateInfo]:
+        """Read certificate metadata from a base64-encoded .p12 payload."""
+        try:
+            decoded = base64.b64decode(base64_data)
+        except (ValueError, binascii.Error) as exc:
+            return Err(
+                DgiiError(
+                    f"Invalid base64 .p12 payload: {exc}",
+                    code=DgiiErrorCode.CERTIFICATE,
+                    cause=exc,
+                )
+            )
+        return self.get_certificate_info_from_bytes(decoded)
+
+    def get_certificate_info_from_bytes(
+        self,
+        data: bytes,
+    ) -> DgiiResult[CertificateInfo]:
+        """Read certificate metadata from raw PKCS#12 bytes."""
+        try:
+            _, certificate = self._load(data)
+        except ValueError as exc:
+            return Err(
+                DgiiError(
+                    f"Unable to extract certificate info: {exc}",
+                    code=DgiiErrorCode.CERTIFICATE,
+                    cause=exc,
+                )
+            )
+        return Ok(
+            CertificateInfo(
+                subject=certificate.subject.rfc4514_string(),
+                issuer=certificate.issuer.rfc4514_string(),
+                valid_from=certificate.not_valid_before_utc,
+                valid_to=certificate.not_valid_after_utc,
+                serial_number=format(certificate.serial_number, "x"),
+            )
+        )