folyo 0.1.0__tar.gz

folyo-0.1.0/.gitignore

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

folyo-0.1.0/LICENSE

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

folyo-0.1.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: folyo
+Version: 0.1.0
+Summary: SDK oficial de Python para la API de Folyo (facturacion electronica chilena, DTE + SII).
+Project-URL: Homepage, https://folyo.cl
+Project-URL: Documentation, https://api.folyo.cl/docs
+Project-URL: Repository, https://github.com/SYCTecnologiaCo/Folyo
+Project-URL: Issues, https://github.com/SYCTecnologiaCo/Folyo/issues
+Author-email: Folyo <soporte@folyo.cl>
+License: MIT
+License-File: LICENSE
+Keywords: boleta,chile,dte,factura-electronica,facturacion,folyo,sii
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+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 :: Office/Business :: Financial :: Accounting
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pip-audit>=2.7; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Folyo — SDK oficial de Python
+
+SDK de Python para la API de [Folyo](https://folyo.cl): facturacion electronica
+chilena (DTE + SII) standalone. Del codigo al SII, sin escalas.
+
+- Cliente tipado sobre `httpx` (unica dependencia de runtime).
+- Errores tipados con mapeo de los codigos del servidor.
+- Soporte del patron de emision asincrona (encolar + polling con backoff).
+- Idempotencia, override de ambiente del SII y reintentos seguros ante 429/503.
+- Redaccion de secretos (la API key/JWT nunca aparecen en `repr` ni en errores).
+
+## Instalacion
+
+```bash
+pip install folyo
+```
+
+Requiere Python 3.9 o superior.
+
+## Autenticacion
+
+El cliente exige exactamente uno de los dos esquemas:
+
+- **API key** (recomendada para integraciones server-side, no expira). Se envia
+  como header `X-API-Key`. Fija el tenant y la empresa.
+- **JWT Bearer** (sesion de usuario). Se envia como `Authorization: Bearer ...`.
+
+```python
+from folyo import Folyo
+
+# Con API key
+folyo = Folyo(api_key="<tu-api-key>")
+
+# O con un token JWT
+folyo = Folyo(token="eyJhbGciOi...")
+```
+
+Tambien funciona como context manager (cierra el cliente HTTP al salir):
+
+```python
+with Folyo(api_key="<tu-api-key>") as folyo:
+    ...
+```
+
+## Quickstart: emitir una Factura Electronica (DTE 33)
+
+La emision es **asincrona**: `emitir()` encola y devuelve un `job_id`; el helper
+`emitir_y_esperar()` hace el polling por ti hasta que el job termina.
+
+```python
+import uuid
+from folyo import Folyo, DTERequest, Receptor, DetalleLinea
+
+with Folyo(api_key="<tu-api-key>") as folyo:
+    req = DTERequest(
+        tipo_dte=33,  # Factura Electronica
+        receptor=Receptor(
+            rut="12.345.678-9",
+            razon_social="Cliente SpA",
+            giro="Comercio",
+        ),
+        detalle=[
+            DetalleLinea(nombre="Servicio de consultoria", monto=100000),
+        ],
+    )
+
+    # Encolar y esperar el resultado (con Idempotency-Key para reintentar seguro)
+    job = folyo.dte.emitir_y_esperar(req, idempotency_key=str(uuid.uuid4()))
+
+    if job.estado == "completed" and job.result is not None:
+        print("Folio:", job.result.folio)
+        print("Track ID:", job.result.track_id)
+        print("Total:", job.result.monto_total)
+
+        # Descargar el PDF
+        pdf = folyo.dte.descargar_pdf(33, job.result.folio)
+        with open(f"factura-{job.result.folio}.pdf", "wb") as f:
+            f.write(pdf)
+    else:
+        print("La emision fallo:", job.estado)
+```
+
+Si prefieres resolver el resultado por webhook o SSE, usa `emitir()` directo:
+
+```python
+encolada = folyo.dte.emitir(req)
+print(encolada.job_id)  # resuelve luego via webhook dte.emitido o polling
+```
+
+## Manejo de errores
+
+```python
+from folyo import (
+    Folyo,
+    FolyoAuthError,
+    FolyoQuotaError,
+    FolyoRateLimitError,
+    FolyoValidationError,
+    FolyoSiiUnavailableError,
+)
+
+try:
+    folyo.dte.emitir(req)
+except FolyoRateLimitError as e:
+    print("Reintentar en", e.retry_after, "segundos")
+except FolyoQuotaError as e:
+    print("Limite de plan o pago requerido:", e.code)
+except FolyoAuthError:
+    print("Credenciales invalidas o sin permisos")
+except FolyoValidationError as e:
+    print("Datos invalidos:", e.message)
+except FolyoSiiUnavailableError:
+    print("El SII no esta disponible, reintenta mas tarde")
+```
+
+El SDK reintenta automaticamente (con backoff exponencial y respetando
+`Retry-After`) ante `429` y `503` en operaciones seguras: peticiones `GET` y
+emisiones con `Idempotency-Key`.
+
+## Recursos disponibles
+
+| Recurso | Metodos principales |
+|---|---|
+| `folyo.dte` | `emitir`, `get_emision`, `emitir_y_esperar`, `listar_documentos`, `descargar_xml`, `descargar_pdf`, `regenerar_pdf`, `consultar_estado`, `consultar_envio`, `emitidos`, `recibidos`, `contribuyente`, `situacion_tributaria`, `enviar_rcof`, `resumen_rcof` |
+| `folyo.folios` | `info`, `solicitar` |
+| `folyo.rcv` | `periodos`, `periodo`, `sync`, `resumen_iva` |
+| `folyo.clientes` | `listar`, `upsert`, `importar`, `buscar`, `actualizar`, `eliminar` |
+| `folyo.empresa` | `listar`, `seleccionar` |
+| `folyo.acuse` | `registrar`, `pendientes`, `estado` |
+| `folyo.webhooks` | `listar`, `crear`, `actualizar`, `eliminar` |
+| `folyo.api_keys` | `listar`, `crear`, `eliminar` |
+
+Algunos endpoints (clientes, RCV, listado de documentos) requieren "panel
+operativo" y responden `403` en planes solo-API.
+
+## Seguridad
+
+- La API key y el JWT nunca se incluyen en `repr(cliente)` ni en los errores.
+- Los errores exponen solo el mensaje sanitizado del servidor, el codigo
+  estable, el status HTTP y el `request_id`: nunca el cuerpo de la respuesta
+  (que puede traer datos sensibles como el XML firmado o secrets de webhook).
+- El SDK no escribe logs por defecto.
+
+## Licencia
+
+MIT. Ver [LICENSE](./LICENSE).

folyo-0.1.0/README.md

@@ -0,0 +1,146 @@
+# Folyo — SDK oficial de Python
+
+SDK de Python para la API de [Folyo](https://folyo.cl): facturacion electronica
+chilena (DTE + SII) standalone. Del codigo al SII, sin escalas.
+
+- Cliente tipado sobre `httpx` (unica dependencia de runtime).
+- Errores tipados con mapeo de los codigos del servidor.
+- Soporte del patron de emision asincrona (encolar + polling con backoff).
+- Idempotencia, override de ambiente del SII y reintentos seguros ante 429/503.
+- Redaccion de secretos (la API key/JWT nunca aparecen en `repr` ni en errores).
+
+## Instalacion
+
+```bash
+pip install folyo
+```
+
+Requiere Python 3.9 o superior.
+
+## Autenticacion
+
+El cliente exige exactamente uno de los dos esquemas:
+
+- **API key** (recomendada para integraciones server-side, no expira). Se envia
+  como header `X-API-Key`. Fija el tenant y la empresa.
+- **JWT Bearer** (sesion de usuario). Se envia como `Authorization: Bearer ...`.
+
+```python
+from folyo import Folyo
+
+# Con API key
+folyo = Folyo(api_key="<tu-api-key>")
+
+# O con un token JWT
+folyo = Folyo(token="eyJhbGciOi...")
+```
+
+Tambien funciona como context manager (cierra el cliente HTTP al salir):
+
+```python
+with Folyo(api_key="<tu-api-key>") as folyo:
+    ...
+```
+
+## Quickstart: emitir una Factura Electronica (DTE 33)
+
+La emision es **asincrona**: `emitir()` encola y devuelve un `job_id`; el helper
+`emitir_y_esperar()` hace el polling por ti hasta que el job termina.
+
+```python
+import uuid
+from folyo import Folyo, DTERequest, Receptor, DetalleLinea
+
+with Folyo(api_key="<tu-api-key>") as folyo:
+    req = DTERequest(
+        tipo_dte=33,  # Factura Electronica
+        receptor=Receptor(
+            rut="12.345.678-9",
+            razon_social="Cliente SpA",
+            giro="Comercio",
+        ),
+        detalle=[
+            DetalleLinea(nombre="Servicio de consultoria", monto=100000),
+        ],
+    )
+
+    # Encolar y esperar el resultado (con Idempotency-Key para reintentar seguro)
+    job = folyo.dte.emitir_y_esperar(req, idempotency_key=str(uuid.uuid4()))
+
+    if job.estado == "completed" and job.result is not None:
+        print("Folio:", job.result.folio)
+        print("Track ID:", job.result.track_id)
+        print("Total:", job.result.monto_total)
+
+        # Descargar el PDF
+        pdf = folyo.dte.descargar_pdf(33, job.result.folio)
+        with open(f"factura-{job.result.folio}.pdf", "wb") as f:
+            f.write(pdf)
+    else:
+        print("La emision fallo:", job.estado)
+```
+
+Si prefieres resolver el resultado por webhook o SSE, usa `emitir()` directo:
+
+```python
+encolada = folyo.dte.emitir(req)
+print(encolada.job_id)  # resuelve luego via webhook dte.emitido o polling
+```
+
+## Manejo de errores
+
+```python
+from folyo import (
+    Folyo,
+    FolyoAuthError,
+    FolyoQuotaError,
+    FolyoRateLimitError,
+    FolyoValidationError,
+    FolyoSiiUnavailableError,
+)
+
+try:
+    folyo.dte.emitir(req)
+except FolyoRateLimitError as e:
+    print("Reintentar en", e.retry_after, "segundos")
+except FolyoQuotaError as e:
+    print("Limite de plan o pago requerido:", e.code)
+except FolyoAuthError:
+    print("Credenciales invalidas o sin permisos")
+except FolyoValidationError as e:
+    print("Datos invalidos:", e.message)
+except FolyoSiiUnavailableError:
+    print("El SII no esta disponible, reintenta mas tarde")
+```
+
+El SDK reintenta automaticamente (con backoff exponencial y respetando
+`Retry-After`) ante `429` y `503` en operaciones seguras: peticiones `GET` y
+emisiones con `Idempotency-Key`.
+
+## Recursos disponibles
+
+| Recurso | Metodos principales |
+|---|---|
+| `folyo.dte` | `emitir`, `get_emision`, `emitir_y_esperar`, `listar_documentos`, `descargar_xml`, `descargar_pdf`, `regenerar_pdf`, `consultar_estado`, `consultar_envio`, `emitidos`, `recibidos`, `contribuyente`, `situacion_tributaria`, `enviar_rcof`, `resumen_rcof` |
+| `folyo.folios` | `info`, `solicitar` |
+| `folyo.rcv` | `periodos`, `periodo`, `sync`, `resumen_iva` |
+| `folyo.clientes` | `listar`, `upsert`, `importar`, `buscar`, `actualizar`, `eliminar` |
+| `folyo.empresa` | `listar`, `seleccionar` |
+| `folyo.acuse` | `registrar`, `pendientes`, `estado` |
+| `folyo.webhooks` | `listar`, `crear`, `actualizar`, `eliminar` |
+| `folyo.api_keys` | `listar`, `crear`, `eliminar` |
+
+Algunos endpoints (clientes, RCV, listado de documentos) requieren "panel
+operativo" y responden `403` en planes solo-API.
+
+## Seguridad
+
+- La API key y el JWT nunca se incluyen en `repr(cliente)` ni en los errores.
+- Los errores exponen solo el mensaje sanitizado del servidor, el codigo
+  estable, el status HTTP y el `request_id`: nunca el cuerpo de la respuesta
+  (que puede traer datos sensibles como el XML firmado o secrets de webhook).
+- El SDK no escribe logs por defecto.
+
+## Licencia
+
+MIT. Ver [LICENSE](./LICENSE).

folyo-0.1.0/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-0.1.0/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]}***"