folyo 0.1.0__py3-none-any.whl

folyo/__init__.py

@@ -0,0 +1,94 @@
+"""SDK oficial de Python para la API de Folyo.
+
+Folyo es facturacion electronica chilena (DTE + SII). Este SDK envuelve la API
+REST de ``https://api.folyo.cl`` con un cliente tipado, manejo de errores y
+soporte para el patron de emision asincrona.
+
+Ejemplo minimo::
+
+    from folyo import Folyo, DTERequest, Receptor, DetalleLinea
+
+    with Folyo(api_key="<tu-api-key>") as folyo:
+        req = DTERequest(
+            tipo_dte=33,
+            receptor=Receptor(rut="12.345.678-9", razon_social="Cliente SpA"),
+            detalle=[DetalleLinea(nombre="Servicio", monto=100000)],
+        )
+        job = folyo.dte.emitir_y_esperar(req)
+        print(job.result.folio)
+"""
+
+from __future__ import annotations
+
+from ._redact import redact
+from .client import DEFAULT_BASE_URL, USER_AGENT, Folyo, __version__
+from .errors import (
+    FolyoAuthError,
+    FolyoConflictError,
+    FolyoConnectionError,
+    FolyoError,
+    FolyoNotFoundError,
+    FolyoQuotaError,
+    FolyoRateLimitError,
+    FolyoSiiUnavailableError,
+    FolyoValidationError,
+)
+from .models import (
+    AcuseRequest,
+    ApiKey,
+    ApiKeyCreated,
+    AuthTokens,
+    Cliente,
+    DescuentoGlobal,
+    DetalleLinea,
+    Documento,
+    DTERequest,
+    EmisionEncolada,
+    EmisionJob,
+    EmisionResult,
+    Empresa,
+    FoliosInfo,
+    Receptor,
+    Referencia,
+    Transporte,
+    Webhook,
+    WebhookCreated,
+)
+
+__all__ = [
+    "__version__",
+    "DEFAULT_BASE_URL",
+    "USER_AGENT",
+    "Folyo",
+    "redact",
+    # Errores
+    "FolyoError",
+    "FolyoAuthError",
+    "FolyoQuotaError",
+    "FolyoValidationError",
+    "FolyoNotFoundError",
+    "FolyoConflictError",
+    "FolyoRateLimitError",
+    "FolyoSiiUnavailableError",
+    "FolyoConnectionError",
+    # Modelos
+    "DTERequest",
+    "Receptor",
+    "DetalleLinea",
+    "DescuentoGlobal",
+    "Referencia",
+    "Transporte",
+    "EmisionEncolada",
+    "EmisionResult",
+    "EmisionJob",
+    "Documento",
+    "FoliosInfo",
+    "Cliente",
+    "Empresa",
+    "Webhook",
+    "WebhookCreated",
+    "ApiKey",
+    "ApiKeyCreated",
+    "AcuseRequest",
+    "AuthTokens",
+]

folyo/_redact.py

@@ -0,0 +1,26 @@
+"""Utilidades de redaccion de secretos.
+
+El SDK no debe filtrar credenciales en ``repr``, logs ni telemetria. Esta
+funcion enmascara cualquier valor sensible mostrando solo una pista minima.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+__all__ = ["redact"]
+
+
+def redact(value: Optional[str]) -> str:
+    """Devuelve una version enmascarada y segura de un secreto.
+
+    - ``None`` o cadena vacia -> ``"None"``.
+    - Valores cortos -> ``"***"`` (sin pistas, no hay suficiente entropia).
+    - Valores largos -> primeros 4 caracteres + ``"***"`` (ej. ``"stri***"``),
+      util para distinguir keys sin revelar el secreto.
+    """
+    if not value:
+        return "None"
+    if len(value) <= 8:
+        return "***"
+    return f"{value[:4]}***"

folyo/client.py

@@ -0,0 +1,296 @@
+"""Cliente HTTP del SDK de Folyo.
+
+``Folyo`` envuelve ``httpx.Client``, arma los headers de autenticacion, parsea
+el envelope ``{ok, data}`` / ``{ok, error, code}``, mapea errores a la
+jerarquia tipada y reintenta con backoff exponencial ante 429/503 cuando es
+seguro hacerlo.
+"""
+
+from __future__ import annotations
+
+import random
+import time
+from types import TracebackType
+from typing import Any, Dict, Mapping, NoReturn, Optional, Type
+
+import httpx
+
+from ._redact import redact
+from .errors import (
+    FolyoAuthError,
+    FolyoConflictError,
+    FolyoConnectionError,
+    FolyoError,
+    FolyoNotFoundError,
+    FolyoQuotaError,
+    FolyoRateLimitError,
+    FolyoSiiUnavailableError,
+    FolyoValidationError,
+)
+from .resources import (
+    AcuseResource,
+    ApiKeysResource,
+    ClientesResource,
+    DteResource,
+    EmpresaResource,
+    FoliosResource,
+    RcvResource,
+    WebhooksResource,
+)
+
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://api.folyo.cl"
+USER_AGENT = f"folyo-sdk-python/{__version__}"
+
+# Codigos HTTP que reintentamos cuando la operacion es segura.
+_RETRYABLE_STATUS = (429, 503)
+
+
+class Folyo:
+    """Cliente sincrono de la API de Folyo.
+
+    Exige exactamente uno de ``api_key`` o ``token`` (XOR):
+
+    - ``api_key``: se envia como header ``X-API-Key`` (valor opaco, sin asumir
+      prefijo). Fija tenant y empresa. Recomendada para integraciones server-side.
+    - ``token``: JWT que se envia como ``Authorization: Bearer <token>``.
+
+    Ejemplo::
+
+        with Folyo(api_key="<tu-api-key>") as folyo:
+            job = folyo.dte.emitir(req)
+            resultado = folyo.dte.emitir_y_esperar(req)
+
+    Args:
+        api_key: API key opaca (XOR con ``token``).
+        token: JWT de sesion (XOR con ``api_key``).
+        base_url: URL base de la API (default produccion).
+        timeout: timeout por request en segundos.
+        max_retries: reintentos ante 429/503 en operaciones seguras.
+        transport: ``httpx`` transport custom (util para tests con respx/mock).
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        token: Optional[str] = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        transport: Optional[httpx.BaseTransport] = None,
+    ) -> None:
+        if bool(api_key) == bool(token):
+            raise ValueError("Debe entregar exactamente uno de 'api_key' o 'token'.")
+
+        self._api_key = api_key
+        self._token = token
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max(0, int(max_retries))
+
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            transport=transport,
+            headers={"User-Agent": USER_AGENT, "Accept": "application/json"},
+        )
+
+        # Recursos
+        self.dte = DteResource(self)
+        self.folios = FoliosResource(self)
+        self.rcv = RcvResource(self)
+        self.clientes = ClientesResource(self)
+        self.empresa = EmpresaResource(self)
+        self.acuse = AcuseResource(self)
+        self.webhooks = WebhooksResource(self)
+        self.api_keys = ApiKeysResource(self)
+
+    # -- Context manager -----------------------------------------------------
+
+    def __enter__(self) -> "Folyo":
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc: Optional[BaseException],
+        tb: Optional[TracebackType],
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Cierra el cliente HTTP subyacente."""
+        self._client.close()
+
+    # -- Repr seguro ---------------------------------------------------------
+
+    def __repr__(self) -> str:
+        auth = (
+            f"api_key={redact(self._api_key)}"
+            if self._api_key is not None
+            else f"token={redact(self._token)}"
+        )
+        return f"Folyo(base_url={self.base_url!r}, {auth})"
+
+    # -- Headers -------------------------------------------------------------
+
+    def _auth_headers(self) -> Dict[str, str]:
+        if self._api_key is not None:
+            return {"X-API-Key": self._api_key}
+        return {"Authorization": f"Bearer {self._token}"}
+
+    # -- Request core --------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Mapping[str, Any]] = None,
+        json: Optional[Any] = None,
+        extra_headers: Optional[Mapping[str, str]] = None,
+        idempotency_key: Optional[str] = None,
+        sii_ambiente: Optional[str] = None,
+        expect_binary: bool = False,
+    ) -> Any:
+        """Ejecuta un request, parsea el envelope y mapea errores.
+
+        Devuelve el contenido de ``data`` (dict/list/escalar) o, si
+        ``expect_binary`` es True, los bytes crudos de la respuesta. Los
+        recursos hacen el cast al modelo concreto.
+        """
+        headers: Dict[str, str] = dict(self._auth_headers())
+        if extra_headers:
+            headers.update(extra_headers)
+        if idempotency_key is not None:
+            headers["Idempotency-Key"] = idempotency_key
+        if sii_ambiente is not None:
+            headers["X-SII-Ambiente"] = sii_ambiente
+
+        # Solo reintentamos operaciones idempotentes: GET, o emision con
+        # Idempotency-Key (reintentar es seguro, no quema folio nuevo).
+        is_safe = method.upper() == "GET" or idempotency_key is not None
+
+        attempt = 0
+        while True:
+            try:
+                response = self._client.request(
+                    method,
+                    path,
+                    params=params,
+                    json=json,
+                    headers=headers,
+                )
+            except httpx.TimeoutException as exc:
+                raise FolyoConnectionError(
+                    "Timeout al conectar con la API de Folyo."
+                ) from exc
+            except httpx.TransportError as exc:
+                # No incluimos str(exc): puede traer la URL con datos sensibles.
+                raise FolyoConnectionError(
+                    "No se pudo conectar con la API de Folyo."
+                ) from exc
+
+            if response.status_code in _RETRYABLE_STATUS and is_safe and attempt < self.max_retries:
+                delay = self._retry_delay(response, attempt)
+                attempt += 1
+                time.sleep(delay)
+                continue
+
+            return self._handle_response(response, expect_binary=expect_binary)
+
+    def _retry_delay(self, response: httpx.Response, attempt: int) -> float:
+        """Calcula el backoff: respeta ``Retry-After`` o usa backoff exponencial."""
+        retry_after = self._parse_retry_after(response)
+        if retry_after is not None:
+            return retry_after
+        # Backoff exponencial con jitter: 0.5, 1, 2, ... (+- jitter).
+        base: float = 0.5 * float(2**attempt)
+        jitter: float = random.uniform(0, 0.25)
+        return base + jitter
+
+    @staticmethod
+    def _parse_retry_after(response: httpx.Response) -> Optional[float]:
+        raw = response.headers.get("Retry-After")
+        if raw is None:
+            return None
+        try:
+            return float(raw)
+        except (TypeError, ValueError):
+            return None
+
+    def _handle_response(self, response: httpx.Response, *, expect_binary: bool) -> Any:
+        request_id = response.headers.get("X-Request-Id") or response.headers.get(
+            "X-Request-ID"
+        )
+
+        if expect_binary and response.is_success:
+            return response.content
+
+        # Intentamos parsear el envelope JSON.
+        try:
+            body = response.json()
+        except ValueError:
+            body = None
+
+        if response.is_success:
+            if isinstance(body, dict) and "data" in body:
+                return body["data"]
+            # Algunas respuestas (ej. /health) no usan envelope.
+            return body if isinstance(body, dict) else {}
+
+        self._raise_for_error(response, body, request_id)
+
+    def _raise_for_error(
+        self,
+        response: httpx.Response,
+        body: Optional[Any],
+        request_id: Optional[str],
+    ) -> NoReturn:
+        status = response.status_code
+        code: Optional[str] = None
+        message = ""
+        if isinstance(body, dict):
+            raw_code = body.get("code")
+            code = raw_code if isinstance(raw_code, str) else None
+            raw_msg = body.get("error")
+            message = raw_msg if isinstance(raw_msg, str) else ""
+        if not message:
+            message = f"La API respondio con HTTP {status}."
+
+        retry_after = self._parse_retry_after(response)
+
+        if status == 429:
+            raise FolyoRateLimitError(
+                message,
+                status=status,
+                code=code or "RATE_LIMITED",
+                request_id=request_id,
+                retry_after=retry_after,
+            )
+        if status in (502, 503, 504):
+            raise FolyoSiiUnavailableError(
+                message,
+                status=status,
+                code=code,
+                request_id=request_id,
+                retry_after=retry_after,
+            )
+        if status in (401, 403):
+            raise FolyoAuthError(message, status=status, code=code, request_id=request_id)
+        if status == 402:
+            raise FolyoQuotaError(message, status=status, code=code, request_id=request_id)
+        if status == 404:
+            raise FolyoNotFoundError(message, status=status, code=code, request_id=request_id)
+        if status == 409:
+            raise FolyoConflictError(message, status=status, code=code, request_id=request_id)
+        if status in (400, 422):
+            raise FolyoValidationError(message, status=status, code=code, request_id=request_id)
+
+        # PLAN_LIMIT/PLAN_REQUIRED pueden llegar como 403 (ya cubierto) pero por
+        # si el server cambia, mapeamos por codigo a quota.
+        if code in ("PLAN_LIMIT", "PLAN_REQUIRED", "PAYMENT_REQUIRED"):
+            raise FolyoQuotaError(message, status=status, code=code, request_id=request_id)
+
+        raise FolyoError(message, status=status, code=code, request_id=request_id)

folyo/errors.py

@@ -0,0 +1,144 @@
+"""Jerarquia de errores del SDK de Folyo.
+
+Los errores NUNCA incluyen el cuerpo de la respuesta: este puede contener datos
+sensibles (la clave tributaria del SII, el contenido de un .pfx, el XML firmado
+o el secret de un webhook). Solo se exponen el mensaje sanitizado del servidor,
+el codigo estable, el status HTTP y el request id (si el servidor lo entrega).
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+__all__ = [
+    "FolyoError",
+    "FolyoAuthError",
+    "FolyoQuotaError",
+    "FolyoValidationError",
+    "FolyoNotFoundError",
+    "FolyoConflictError",
+    "FolyoRateLimitError",
+    "FolyoSiiUnavailableError",
+    "FolyoConnectionError",
+]
+
+
+class FolyoError(Exception):
+    """Error base de todos los errores del SDK.
+
+    Atributos:
+        message: mensaje legible y sanitizado del servidor (sin datos sensibles).
+        status: codigo HTTP de la respuesta (None en errores de conexion).
+        code: codigo estable de error del servidor (ej. ``PLAN_LIMIT``).
+        request_id: identificador de la peticion para soporte (si el server lo da).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: Optional[int] = None,
+        code: Optional[str] = None,
+        request_id: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+
+    def __str__(self) -> str:
+        parts = [self.message or self.__class__.__name__]
+        meta = []
+        if self.status is not None:
+            meta.append(f"status={self.status}")
+        if self.code:
+            meta.append(f"code={self.code}")
+        if self.request_id:
+            meta.append(f"request_id={self.request_id}")
+        if meta:
+            parts.append(f"({', '.join(meta)})")
+        return " ".join(parts)
+
+    def __repr__(self) -> str:
+        # No exponemos el cuerpo de la respuesta: solo metadatos seguros.
+        return (
+            f"{self.__class__.__name__}(message={self.message!r}, "
+            f"status={self.status!r}, code={self.code!r}, request_id={self.request_id!r})"
+        )
+
+
+class FolyoAuthError(FolyoError):
+    """Fallo de autenticacion/autorizacion (401/403).
+
+    Cubre ``UNAUTHORIZED``, ``INVALID_TOKEN``, ``TOKEN_EXPIRED``,
+    ``PASSWORD_CHANGED``, ``FORBIDDEN``, ``INSUFFICIENT_SCOPE``,
+    ``ACCOUNT_SUSPENDED``.
+    """
+
+
+class FolyoQuotaError(FolyoError):
+    """Limite de plan o pago requerido (402/403).
+
+    Cubre ``PLAN_LIMIT``, ``PLAN_REQUIRED`` y ``PAYMENT_REQUIRED``.
+    """
+
+
+class FolyoValidationError(FolyoError):
+    """Peticion invalida (400): body, params o headers mal formados."""
+
+
+class FolyoNotFoundError(FolyoError):
+    """Recurso no encontrado (404)."""
+
+
+class FolyoConflictError(FolyoError):
+    """Conflicto (409).
+
+    Incluye ``IDEMPOTENCY_KEY_CONFLICT`` (misma Idempotency-Key con cuerpo
+    distinto) y ``TIMBRAJE_NO_AUTORIZADO``.
+    """
+
+
+class FolyoRateLimitError(FolyoError):
+    """Demasiadas peticiones (429).
+
+    Expone ``retry_after`` (segundos sugeridos por el header ``Retry-After``).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: Optional[int] = None,
+        code: Optional[str] = None,
+        request_id: Optional[str] = None,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        super().__init__(message, status=status, code=code, request_id=request_id)
+        self.retry_after = retry_after
+
+
+class FolyoSiiUnavailableError(FolyoError):
+    """SII o un servicio aguas abajo no disponible (502/503/504).
+
+    Cubre ``SII_UNAVAILABLE``, ``SII_TIMEOUT``, ``SII_AUTH_FAILED``,
+    ``SII_ERROR``, ``SII_CAPTCHA_REQUIRED``, ``FOLIOS_REQUESTING`` y
+    ``QUEUE_UNAVAILABLE``. Expone ``retry_after`` cuando el server lo entrega.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: Optional[int] = None,
+        code: Optional[str] = None,
+        request_id: Optional[str] = None,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        super().__init__(message, status=status, code=code, request_id=request_id)
+        self.retry_after = retry_after
+
+
+class FolyoConnectionError(FolyoError):
+    """No se pudo conectar con la API (timeout de red, DNS, TLS, etc.)."""