libredte-lib-sdk 0.1.0__py3-none-any.whl

libredte_lib_sdk/billing/identifier/models.py

@@ -0,0 +1,37 @@
+"""DTO del componente `billing.identifier`."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from ..common import XmlPayloadMixin
+
+
+@dataclass(frozen=True, slots=True)
+class Caf(XmlPayloadMixin):
+    """
+    CAF (Código de Autorización de Folios) de un emisor.
+
+    Expone los campos más usados directamente; `.raw` trae el `dict`
+    completo que devuelve la API (incluye además, entre otros, la
+    llave RSA del CAF y si está vigente) por si algo más específico
+    hace falta más adelante.
+    """
+
+    tipo_documento: int
+    folio_desde: int
+    folio_hasta: int
+    xml_base64: str
+    raw: dict[str, Any]
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> Caf:
+        """Construye un `Caf` desde el `data` que devuelve la API."""
+        return cls(
+            tipo_documento=data['tipoDocumento'],
+            folio_desde=data['folioDesde'],
+            folio_hasta=data['folioHasta'],
+            xml_base64=data['xml'],
+            raw=data,
+        )

libredte_lib_sdk/billing/integration/__init__.py

@@ -0,0 +1,17 @@
+"""Componente `billing.integration`: integración con el SII."""
+
+from __future__ import annotations
+
+from ...client import ApiClient
+from .models import SendResult, SiiStatus
+from .sii_dte import SiiDteService
+
+__all__ = ['IntegrationComponent', 'SendResult', 'SiiDteService', 'SiiStatus']
+
+
+class IntegrationComponent:
+    """Agrupa los servicios de `billing.integration`."""
+
+    def __init__(self, client: ApiClient) -> None:
+        """Crea los servicios del componente sobre el `ApiClient` dado."""
+        self.sii_dte = SiiDteService(client)

libredte_lib_sdk/billing/integration/models.py

@@ -0,0 +1,46 @@
+"""DTO del componente `billing.integration`."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+def _first_present(data: dict[str, Any], *keys: str) -> Any:
+    for key in keys:
+        if key in data:
+            return data[key]
+    return None
+
+
+@dataclass(frozen=True, slots=True)
+class SendResult:
+    """Resultado del envío de un DTE al SII."""
+
+    track_id: int | None
+    raw: dict[str, Any]
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> SendResult:
+        """Construye un `SendResult` desde el `data` que devuelve la API."""
+        return cls(
+            track_id=_first_present(data, 'trackId', 'track_id'),
+            raw=data,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class SiiStatus:
+    """Estado de revisión de un envío al SII."""
+
+    raw: dict[str, Any]
+
+    @property
+    def status(self) -> Any:
+        """Estado informado por el SII, si la respuesta lo incluyó."""
+        return _first_present(self.raw, 'status', 'estado', 'state')
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> SiiStatus:
+        """Construye un `SiiStatus` desde el `data` que devuelve la API."""
+        return cls(raw=data)

libredte_lib_sdk/billing/integration/sii_dte.py

@@ -0,0 +1,83 @@
+"""Servicio para `billing.integration.sii_dte`."""
+
+from __future__ import annotations
+
+from ...client import ApiClient
+from ..enums import SiiEnvironment
+from ..trading_parties.models import Certificate
+from .models import SendResult, SiiStatus
+
+
+class SiiDteService:
+    """
+    Envío y consulta de estado ante el SII (`billing.integration.sii_dte`).
+
+    Solo cubre `sendXmlDocument` y `checkXmlDocumentSentStatus` — el
+    worker expone más operaciones (ej. validar un documento ya aceptado,
+    o pedir el estado por correo), no incluidas acá.
+
+    Ambas operaciones autentican contra el SII real con el certificado
+    dado; un certificado no válido para el SII (ej. uno autofirmado de
+    prueba, como los que genera `TradingPartiesComponent
+    .mandatario_manager.create_fake_certificate`) resulta en un
+    `LibreDteApiError` (la propia excepción de autenticación del SII,
+    accesible vía `.php_class`), no en una excepción distinta.
+    """
+
+    _SEND_OPERATION = 'billing.integration.sii_dte::sendXmlDocument'
+    _STATUS_OPERATION = (
+        'billing.integration.sii_dte::checkXmlDocumentSentStatus'
+    )
+
+    def __init__(self, client: ApiClient) -> None:
+        """Guarda el `ApiClient` compartido usado para llamar a la API."""
+        self._client = client
+
+    def send(
+        self,
+        envelope_xml_base64: str,
+        *,
+        certificate: Certificate,
+        company_rut: str,
+        environment: SiiEnvironment = SiiEnvironment.CERTIFICATION,
+        compress: bool = False,
+        retries: int | None = None,
+    ) -> SendResult:
+        """
+        Envía el sobre `EnvioDTE` al SII y devuelve su Track ID.
+
+        `envelope_xml_base64` es el XML en base64 del sobre ya armado
+        (`Envelope.xml_base64` de `DocumentDispatcherService.create`).
+        """
+        data = self._client.call(
+            self._SEND_OPERATION,
+            request={
+                'certificate': certificate.to_payload(),
+                'options': {'environment': int(environment)},
+            },
+            doc=envelope_xml_base64,
+            company=company_rut,
+            compress=compress,
+            retries=retries,
+        )
+        return SendResult.from_api(data)
+
+    def check_status(
+        self,
+        track_id: int,
+        *,
+        certificate: Certificate,
+        company_rut: str,
+        environment: SiiEnvironment = SiiEnvironment.CERTIFICATION,
+    ) -> SiiStatus:
+        """Consulta el estado de un envío al SII mediante su Track ID."""
+        data = self._client.call(
+            self._STATUS_OPERATION,
+            request={
+                'certificate': certificate.to_payload(),
+                'options': {'environment': int(environment)},
+            },
+            trackId=track_id,
+            company=company_rut,
+        )
+        return SiiStatus.from_api(data)

libredte_lib_sdk/billing/trading_parties/__init__.py

@@ -0,0 +1,21 @@
+"""Componente `billing.trading_parties`: partes comerciales de un DTE."""
+
+from __future__ import annotations
+
+from ...client import ApiClient
+from .mandatario_manager import MandatarioManagerService
+from .models import Certificate
+
+__all__ = [
+    'Certificate',
+    'MandatarioManagerService',
+    'TradingPartiesComponent',
+]
+
+
+class TradingPartiesComponent:
+    """Agrupa los servicios de `billing.trading_parties`."""
+
+    def __init__(self, client: ApiClient) -> None:
+        """Crea los servicios del componente sobre el `ApiClient` dado."""
+        self.mandatario_manager = MandatarioManagerService(client)

libredte_lib_sdk/billing/trading_parties/mandatario_manager.py

@@ -0,0 +1,45 @@
+"""Servicio para `billing.trading_parties.mandatario_manager`."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ...client import ApiClient
+from .models import Certificate
+
+
+class MandatarioManagerService:
+    """
+    Gestión del mandatario (representante) dueño de un certificado.
+
+    Solo cubre `createFakeCertificate`: generar un certificado ficticio
+    para pruebas o desarrollo, sin depender de un certificado real. El
+    worker también expone `createFromCertificate` (reconstruir el
+    mandatario a partir de un certificado real), no incluida acá.
+    """
+
+    _CREATE_FAKE_OPERATION = (
+        'billing.trading_parties.mandatario_manager::createFakeCertificate'
+    )
+
+    def __init__(self, client: ApiClient) -> None:
+        """Guarda el `ApiClient` compartido usado para llamar a la API."""
+        self._client = client
+
+    def create_fake_certificate(
+        self,
+        mandatario: dict[str, Any],
+    ) -> Certificate:
+        """
+        Genera un certificado digital ficticio para `mandatario`.
+
+        Únicamente para pruebas/desarrollo: el certificado resultante es
+        autofirmado por una CA de prueba de LibreDTE, no sirve para
+        autenticar de verdad ante el SII. `mandatario` es un `dict` con
+        `run`/`nombre`/`email`, tal como lo espera la API.
+        """
+        data = self._client.call(
+            self._CREATE_FAKE_OPERATION,
+            mandatario=mandatario,
+        )
+        return Certificate.from_api(data)

libredte_lib_sdk/billing/trading_parties/models.py

@@ -0,0 +1,38 @@
+"""DTO del componente `billing.trading_parties`."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class Certificate:
+    """
+    Certificado digital (firma electrónica) de un mandatario/emisor.
+
+    `to_payload()` arma el `dict` que espera la API en cualquier
+    operación que reciba un certificado (`certificate`/`privateKey`).
+    `from_api()` hace el camino inverso, para el certificado ficticio
+    que devuelve `MandatarioManagerService.create_fake_certificate()`
+    (ahí la API usa otros nombres de campo: `cert`/`pkey`).
+    """
+
+    certificate: str
+    private_key: str
+    password: str | None = None
+
+    def to_payload(self) -> dict[str, Any]:
+        """Payload esperado por la API para un certificado."""
+        payload: dict[str, Any] = {
+            'certificate': self.certificate,
+            'privateKey': self.private_key,
+        }
+        if self.password is not None:
+            payload['password'] = self.password
+        return payload
+
+    @classmethod
+    def from_api(cls, data: dict[str, Any]) -> Certificate:
+        """Construye un `Certificate` desde un certificado ficticio."""
+        return cls(certificate=data['cert'], private_key=data['pkey'])

libredte_lib_sdk/client.py

@@ -0,0 +1,184 @@
+"""Cliente HTTP delgado para la API de LibreDTE Lib (`core.libredte.cl`)."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Self
+
+import httpx
+
+from .exceptions import (
+    LibreDteApiError,
+    LibreDteConnectionError,
+    LibreDteRateLimitError,
+)
+
+DEFAULT_BASE_URL = 'https://core.libredte.cl/api'
+DEFAULT_TIMEOUT = 30.0
+_HTTP_TOO_MANY_REQUESTS = 429
+
+
+class ApiClient:
+    """
+    Despacha operaciones contra la API de LibreDTE Lib.
+
+    Traduce un `operation_id` con el formato
+    `paquete.componente.worker::operacion` (el mismo que usa
+    `libredte-lib-core-dispatcher`) a la ruta HTTP equivalente:
+    `POST /{paquete}/{componente}/{worker}/{operacion}`.
+
+    No sabe nada de DTE ni de reglas de negocio: solo hace la llamada
+    HTTP y normaliza la respuesta (el `data` del sobre JSON en éxito,
+    los bytes crudos si la respuesta no es JSON, o una excepción tipada
+    si la API respondió un error). La orquestación vive en
+    `billing/*/*.py`.
+
+    Por defecto apunta a `core.libredte.cl`. Es configurable (`base_url`
+    o la variable de entorno `LIBREDTE_LIB_SDK_BASE_URL`) para apuntar a
+    `pro.libredte.cl` u otro ambiente.
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        *,
+        api_token: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        """Configura la URL base, autenticación opcional y cliente HTTP."""
+        self._base_url = (
+            base_url
+            or os.environ.get('LIBREDTE_LIB_SDK_BASE_URL')
+            or DEFAULT_BASE_URL
+        ).rstrip('/')
+        self._api_token = api_token or os.environ.get(
+            'LIBREDTE_LIB_SDK_TOKEN',
+        )
+        self._client = http_client or httpx.Client(timeout=timeout)
+        self._owns_client = http_client is None
+
+    def close(self) -> None:
+        """Cierra la conexión HTTP, si este cliente es dueño de ella."""
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> Self:
+        """Permite usar `ApiClient` como context manager."""
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        """Cierra la conexión HTTP al salir del context manager."""
+        self.close()
+
+    def call(self, operation_id: str, **parameters: Any) -> Any:
+        """
+        Ejecuta `operation_id` con `parameters` y devuelve su resultado.
+
+        `parameters` se manda tal cual como el objeto `parameters` del
+        body JSON que espera la API (ej. `bag=...`, `request=...`).
+        """
+        url = f'{self._base_url}/{self._operation_path(operation_id)}'
+
+        try:
+            response = self._client.post(
+                url,
+                json={'parameters': parameters},
+                headers=self._headers(),
+            )
+        except httpx.RequestError as error:
+            raise LibreDteConnectionError(
+                f'No fue posible conectar con la API de LibreDTE Lib '
+                f'({operation_id}): {error}',
+            ) from error
+
+        self._raise_for_rate_limit(operation_id, response)
+        return self._parse_response(operation_id, response)
+
+    def _headers(self) -> dict[str, str]:
+        headers = {'Accept': 'application/json'}
+        if self._api_token:
+            headers['Authorization'] = f'Bearer {self._api_token}'
+        return headers
+
+    @staticmethod
+    def _operation_path(operation_id: str) -> str:
+        try:
+            namespace, operation = operation_id.split('::', 1)
+            package, component, worker = namespace.split('.', 2)
+        except ValueError as error:
+            raise ValueError(
+                f'operation_id invalido: {operation_id!r}. Formato '
+                "esperado: 'paquete.componente.worker::operacion'.",
+            ) from error
+        return f'{package}/{component}/{worker}/{operation}'
+
+    @staticmethod
+    def _raise_for_rate_limit(
+        operation_id: str,
+        response: httpx.Response,
+    ) -> None:
+        """
+        Levanta `LibreDteRateLimitError` si la API frenó la solicitud.
+
+        La API expone `X-RateLimit-Limit`/`X-RateLimit-Remaining` en
+        toda respuesta. Se confía solo en el status code (`429`) más los
+        headers estándar de HTTP (`Retry-After`, `X-RateLimit-*`), no en
+        un shape de body particular.
+        """
+        if response.status_code != _HTTP_TOO_MANY_REQUESTS:
+            return
+
+        def _int_header(name: str) -> int | None:
+            value = response.headers.get(name)
+            return int(value) if value and value.isdigit() else None
+
+        def _retry_after() -> float | None:
+            value = response.headers.get('retry-after')
+            if value is None:
+                return None
+            try:
+                return float(value)
+            except ValueError:
+                return None
+
+        detail = response.text
+        try:
+            body = response.json()
+        except ValueError:
+            body = {}
+        if isinstance(body, dict) and body.get('detail'):
+            detail = body['detail']
+
+        raise LibreDteRateLimitError(
+            operation_id=operation_id,
+            detail=detail,
+            retry_after=_retry_after(),
+            limit=_int_header('x-ratelimit-limit'),
+            remaining=_int_header('x-ratelimit-remaining'),
+        )
+
+    @staticmethod
+    def _parse_response(operation_id: str, response: httpx.Response) -> Any:
+        content_type = response.headers.get('content-type', '')
+
+        if 'application/json' not in content_type:
+            if response.is_error:
+                raise LibreDteApiError(
+                    operation_id=operation_id,
+                    status_code=response.status_code,
+                    title='Respuesta de error inesperada (no-JSON).',
+                    detail=response.text,
+                )
+            return response.content
+
+        body = response.json()
+
+        if response.is_success and isinstance(body, dict) and 'data' in body:
+            return body['data']
+
+        raise LibreDteApiError.from_problem_details(
+            operation_id=operation_id,
+            status_code=response.status_code,
+            body=body if isinstance(body, dict) else {},
+        )

libredte_lib_sdk/exceptions.py

@@ -0,0 +1,117 @@
+"""Excepciones del SDK de LibreDTE Lib."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class LibreDteSdkError(Exception):
+    """Cualquier error propio de `libredte_lib_sdk`."""
+
+
+class LibreDteConnectionError(LibreDteSdkError):
+    """No fue posible completar la conexión HTTP con la API."""
+
+
+class LibreDteApiError(LibreDteSdkError):
+    """
+    La API de LibreDTE Lib respondió un error para una operación.
+
+    Envuelve el `Problem Details` (RFC 7807) que la API entrega en sus
+    respuestas de error: `type`/`title`/`detail`/`instance`/`extensions`.
+    `php_class` expone la clase de la excepción PHP real (si la API la
+    informó en `extensions.throwable.class`), útil para distinguir
+    errores de negocio (ej. `DocumentException`) de errores de
+    infraestructura sin tener que parsear `detail`.
+    """
+
+    def __init__(
+        self,
+        *,
+        operation_id: str,
+        status_code: int,
+        title: str,
+        detail: str = '',
+        problem_type: str = 'about:blank',
+        instance: str = '',
+        extensions: dict[str, Any] | None = None,
+    ) -> None:
+        """Guarda el detalle del error tal como lo informó la API."""
+        self.operation_id = operation_id
+        self.status_code = status_code
+        self.title = title
+        self.detail = detail
+        self.problem_type = problem_type
+        self.instance = instance or operation_id
+        self.extensions = extensions or {}
+        message = f'[{operation_id}] {title}'
+        if detail:
+            message = f'{message}: {detail}'
+        super().__init__(message)
+
+    @property
+    def php_class(self) -> str | None:
+        """Clase PHP real detrás del error, si la API la informó."""
+        throwable = self.extensions.get('throwable')
+        if isinstance(throwable, dict):
+            return throwable.get('class')
+        return None
+
+    @classmethod
+    def from_problem_details(
+        cls,
+        *,
+        operation_id: str,
+        status_code: int,
+        body: dict[str, Any],
+    ) -> LibreDteApiError:
+        """Construye la excepción a partir de un body Problem Details."""
+        return cls(
+            operation_id=operation_id,
+            status_code=status_code,
+            title=body.get('title') or 'Error desconocido de la API.',
+            detail=body.get('detail') or '',
+            problem_type=body.get('type') or 'about:blank',
+            instance=body.get('instance') or operation_id,
+            extensions=body.get('extensions'),
+        )
+
+
+class LibreDteRateLimitError(LibreDteApiError):
+    """
+    La API rechazó la llamada por exceso de solicitudes (HTTP 429).
+
+    `retry_after` trae el valor del header `Retry-After` en segundos
+    (`None` si la API no lo informó). `limit`/`remaining` traen
+    `X-RateLimit-Limit`/`X-RateLimit-Remaining` cuando la API los
+    informa. No hay retry/backoff automático: quien llame decide si
+    reintentar, y cuándo, con esta información.
+    """
+
+    def __init__(
+        self,
+        *,
+        operation_id: str,
+        status_code: int = 429,
+        title: str = 'Límite de solicitudes excedido.',
+        detail: str = '',
+        problem_type: str = 'about:blank',
+        instance: str = '',
+        extensions: dict[str, Any] | None = None,
+        retry_after: float | None = None,
+        limit: int | None = None,
+        remaining: int | None = None,
+    ) -> None:
+        """Guarda el detalle del error de rate limit, con sus headers."""
+        super().__init__(
+            operation_id=operation_id,
+            status_code=status_code,
+            title=title,
+            detail=detail,
+            problem_type=problem_type,
+            instance=instance,
+            extensions=extensions,
+        )
+        self.retry_after = retry_after
+        self.limit = limit
+        self.remaining = remaining

libredte_lib_sdk/sdk.py

@@ -0,0 +1,79 @@
+"""Punto de entrada único del SDK: `LibreDTE`."""
+
+from __future__ import annotations
+
+from typing import Self
+
+import httpx
+
+from .billing import BillingPackage
+from .client import DEFAULT_TIMEOUT, ApiClient
+
+
+class LibreDTE:
+    """
+    Fachada del SDK: agrupa los paquetes de la API (por ahora, `billing`).
+
+    Uso típico (ver `README.rst` para el detalle de cada DTO):
+
+    .. code-block:: python
+
+        sdk = LibreDTE()
+        doc, ident, tp, sii = (
+            sdk.billing.document,
+            sdk.billing.identifier,
+            sdk.billing.trading_parties,
+            sdk.billing.integration,
+        )
+
+        borrador = doc.builder.build_draft(parsed_data)
+
+        caf = ident.caf_faker.create(emisor, codigo_documento=33)
+        certificate = tp.mandatario_manager.create_fake_certificate(
+            mandatario,
+        )
+        documento = doc.builder.build_signed(
+            parsed_data, caf_xml=caf.xml_base64, certificate=certificate,
+        )
+        sobre = doc.dispatcher.create(
+            documento.xml_base64, certificate=certificate, emisor=emisor_dto,
+        )
+        envio = sii.sii_dte.send(
+            sobre.xml_base64, certificate=certificate, company_rut=rut,
+        )
+        estado = sii.sii_dte.check_status(
+            envio.track_id, certificate=certificate, company_rut=rut,
+        )
+
+        pdf = doc.renderer.render(documento.xml_base64).first
+        pdf_bytes = pdf.content_bytes
+    """
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        *,
+        api_token: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        """Crea el `ApiClient` compartido y los paquetes que lo usan."""
+        self._client = ApiClient(
+            base_url,
+            api_token=api_token,
+            timeout=timeout,
+            http_client=http_client,
+        )
+        self.billing = BillingPackage(self._client)
+
+    def close(self) -> None:
+        """Cierra la conexión HTTP subyacente."""
+        self._client.close()
+
+    def __enter__(self) -> Self:
+        """Permite usar `LibreDTE` como context manager."""
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        """Cierra la conexión HTTP al salir del context manager."""
+        self.close()