openubl 0.1.3__tar.gz

openubl-0.1.3/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  python:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - name: Sync dependencies
+        run: uv sync
+      - name: Run Python tests
+        run: uv run pytest -m "not e2e"
+      - name: Run static sync check
+        run: uv run python scripts/check_sdk_sync.py
+      - name: Build wheel
+        run: uv build
+
+  typescript:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Install & generate
+        run: |
+          cd sdk/typescript
+          npm ci
+          npm run generate
+      - name: Build
+        run: cd sdk/typescript && npm run build
+      - name: Test
+        run: cd sdk/typescript && npm test

openubl-0.1.3/.github/workflows/deploy.yml

@@ -0,0 +1,49 @@
+name: Deploy Docs to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Install dependencies
+        run: cd docs && npm ci
+      - name: Build
+        run: cd docs && npm run build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

openubl-0.1.3/.github/workflows/publish.yml

@@ -0,0 +1,94 @@
+name: Publish Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: "https://registry.npmjs.org"
+      - run: uv sync
+      - run: uv run pytest -m "not e2e"
+      - run: uv run python scripts/check_sdk_sync.py
+      - run: cd sdk/typescript && npm ci && npm run generate && npm run build && npm test
+      - run: uv build
+
+  publish-pypi:
+    needs: build-and-test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v3
+      - run: uv sync
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}
+
+  publish-npm:
+    needs: build-and-test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: "https://registry.npmjs.org"
+      - run: cd sdk/typescript && npm ci && npm run generate && npm run build
+      - run: cd sdk/typescript && npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  release-notes:
+    needs: [publish-pypi, publish-npm]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Generate changelog
+        id: git-cliff
+        uses: orhun/git-cliff-action@v4
+        with:
+          config: cliff.toml
+          args: --latest --strip header
+        env:
+          OUTPUT: CHANGES.md
+          GITHUB_REPO: ${{ github.repository }}
+      - name: Build release body
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          {
+            echo "📦 **PyPI**: [openubl ${VERSION}](https://pypi.org/project/openubl/${VERSION}/)"
+            echo ""
+            echo '```bash'
+            echo "pip install openubl==${VERSION}"
+            echo '```'
+            echo ""
+            echo "📦 **npm**: [@openubl/sdk ${VERSION}](https://www.npmjs.com/package/@openubl/sdk/v/${VERSION})"
+            echo ""
+            echo '```bash'
+            echo "npm install @openubl/sdk@${VERSION}"
+            echo '```'
+            echo ""
+            echo "---"
+            echo ""
+            cat CHANGES.md
+          } > RELEASE_BODY.md
+      - name: Create GitHub Release
+        run: |
+          BODY=$(cat RELEASE_BODY.md)
+          gh release create "$GITHUB_REF_NAME" \
+            --title "Release $GITHUB_REF_NAME" \
+            --notes "$BODY"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

openubl-0.1.3/.gitignore

@@ -0,0 +1,33 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# pytest
+.pytest_cache/
+
+# Node.js
+node_modules/
+
+# OpenAPI Generator metadata
+openapitools.json
+
+# Generated SDK files
+sdk/java/
+sdk/go/
+sdk/python/
+sdk/csharp/
+sdk/typescript/src/openubl-types.ts
+
+# Documentation build output
+docs/dist/
+docs/.astro/
+
+# Local tools (e.g. downloaded binaries)
+.tools/

openubl-0.1.3/.python-version

@@ -0,0 +1 @@
+3.11

openubl-0.1.3/AGENTS.md

@@ -0,0 +1,137 @@
+# openUBL — Contexto para Agentes de IA
+
+## Qué es este proyecto
+
+openUBL es una biblioteca Python para generar, firmar y validar documentos electrónicos UBL 2.1 para SUNAT (Perú). Expone una API REST FastAPI y SDKs generados a partir de OpenAPI.
+
+## Estructura clave
+
+```
+openubl/
+├── src/openubl/           # Biblioteca core Python
+│   ├── models/            # Pydantic models (Invoice, CreditNote, etc.)
+│   ├── api/router.py      # Endpoints FastAPI
+│   ├── main.py            # App FastAPI
+│   ├── renderer.py        # Renderizado Jinja2 → XML UBL
+│   ├── signer.py          # Firma digital XAdES-EPES
+│   ├── validator.py       # Validación SUNAT sobre XML
+│   ├── enricher.py        # Enriquecimiento automático de campos
+│   └── version.py         # check_api_version() para sincronización runtime
+├── sdk/typescript/        # SDK TypeScript (@openubl/sdk)
+│   ├── src/               # Código fuente (client.ts, version.ts, openubl-types.ts)
+│   ├── test/              # Tests Vitest
+│   └── dist/              # Emitido por tsc
+  ├── scripts/
+  │   ├── export_openapi.py      # Exporta openapi.json desde FastAPI
+  │   ├── check_sdk_sync.py      # Valida sincronización de versiones + openapi.json
+  │   ├── bump_version.py        # Bump atómico de versión en todas las fuentes
+  │   └── release.py             # Script único de release (bump, commit, tag, push, rollback)
+  ├── .github/workflows/
+  │   ├── ci.yml                 # Tests y build en PR
+  │   └── publish.yml            # Publica en PyPI + npm y crea GitHub Release
+├── tests/                 # Suite pytest
+├── openapi.json           # Esquema OpenAPI 3.1.0 (single source of truth)
+├── pyproject.toml         # Config Python (openubl)
+└── package.json           # Config root (scripts/docs)
+```
+
+## Convenciones de código
+
+- **Idioma**: Código en inglés, documentación y mensajes de usuario en español.
+- **Python**: `snake_case`, tipado estricto (mypy-friendly), docstrings en español para FastAPI OpenAPI.
+- **TypeScript**: `camelCase`, ES modules (`"type": "module"`), tipos exportados desde `openubl-types.ts`.
+- **Versionado**: SemVer. La versión debe ser idéntica en los 7 archivos. Nunca editar a mano; usar `scripts/bump_version.py`.
+
+## Cómo ejecutar tests
+
+```bash
+# Python (todos excepto E2E)
+uv run pytest -m "not e2e"
+
+# TypeScript SDK
+cd sdk/typescript && npm test
+
+# Sincronización
+uv run python scripts/check_sdk_sync.py
+```
+
+## Cómo crear un release
+
+Cuando un PR se mergea a `main` con un label `release:patch`, `release:minor` o `release:major`:
+
+| Label | Color HEX | Resultado |
+|-------|-----------|-----------|
+| `release:patch` | `#22c55e` | Bugfix → `0.1.0` → `0.1.1` |
+| `release:minor` | `#f59e0b` | Feature → `0.1.0` → `0.2.0` |
+| `release:major` | `#ef4444` | Breaking → `0.1.0` → `1.0.0` |
+
+1. Ejecuta localmente (detecta el label automáticamente):
+   ```bash
+   uv run python scripts/release.py --from-label --push
+   ```
+   > Requiere la CLI `gh` instalada y autenticada.
+
+2. El workflow `.github/workflows/publish.yml` se disparará automáticamente en GitHub Actions por el tag `v*`.
+
+### Flujo manual (fallback)
+
+```bash
+# Bump por tipo
+uv run python scripts/release.py --type minor --push
+
+# O versión exacta
+uv run python scripts/release.py 0.2.0 --push
+```
+
+### Rollback
+
+Si algo sale mal después de crear el release localmente:
+
+```bash
+uv run python scripts/release.py --rollback
+```
+
+Esto elimina el tag local y hace `git reset --hard HEAD~1`.
+
+## Reglas de dominio (no inventar)
+
+### Fuente de verdad obligatoria
+
+Antes de implementar o modificar cualquier regla de validación, formato, catálogo o estructura XML relacionada con SUNAT, **debes consultar primero** la documentación oficial en:
+
+**https://cpe.sunat.gob.pe/guias-y-manuales**
+
+Esta es la fuente autorizada de SUNAT para:
+- Guías de emisión electrónica (factura, boleta, notas de crédito/débito, etc.)
+- Especificaciones técnicas de XML UBL 2.1
+- Catálogos de códigos (tipo de documento, tipo de operación, moneda, etc.)
+- Reglas de validación y rechazo
+- Formatos de firma digital y envío
+
+**Nunca asumas, inventes ni "alucines" reglas SUNAT.** Si la información no está clara en el código existente, busca en la URL oficial antes de escribir código nuevo.
+
+### Reglas del código existente
+
+- Los documentos SUNAT usan catálogos fijos (tipo de documento, moneda, etc.). Están en `src/openubl/models/catalog.py`.
+- La firma digital requiere certificado PEM y clave privada PEM. No inventar formatos.
+- El XML UBL 2.1 generado debe pasar validación SUNAT (`validator.py`) antes del envío.
+- El ambiente beta de SUNAT requiere credenciales reales (`SUNAT_BETA_RUC`); los tests E2E están marcados con `pytest.mark.e2e`.
+
+## Qué NO hacer
+
+- No editar versiones a mano en `__init__.py`, `pyproject.toml`, `package.json`, etc. Usar `bump_version.py`.
+- No modificar `openapi.json` manualmente. Usar `export_openapi.py`.
+- No romper la sincronización entre API y SDKs. Siempre ejecutar `check_sdk_sync.py` antes de un release.
+- No agregar dependencias runtime innecesarias. `urllib.request` ya cubre HTTP simple en Python.
+
+## Endpoints principales (FastAPI)
+
+- `POST /api/v1/invoice/create` → Genera XML de factura/boleta
+- `POST /api/v1/credit-note/create` → Nota de crédito
+- `POST /api/v1/debit-note/create` → Nota de débito
+- `POST /api/v1/voided-documents/create` → Comunicación de baja (RA)
+- `POST /api/v1/summary-documents/create` → Resumen diario (RC)
+- `POST /api/v1/perception/create` → Percepción
+## Contacto / autor
+
+Consulta el repositorio en GitHub para información del mantenedor.

openubl-0.1.3/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.1] - 2026-06-11
+
+### Features
+
+- *(core)* Initial openUBL project with SUNAT electronic invoicing - ([9eeae61](https://github.com/darvin2c/openUBL/commit/9eeae610527ddf49af5307013c66dded77e50e0d))
+- *(docs)* Astro Starlight documentation site - ([f1ad39b](https://github.com/darvin2c/openUBL/commit/f1ad39b670944f3cc8105d994d76b8dd9ca6cebe))
+- *(sdk)* Multi-language SDK generation from OpenAPI - ([3e02820](https://github.com/darvin2c/openUBL/commit/3e02820f513848da9a3061c328793c168c506474))
+<!-- generated by git-cliff -->

openubl-0.1.3/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: openubl
+Version: 0.1.3
+Summary: openUBL - Peruvian SUNAT Electronic Documents Library
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.136.3
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: lxml>=6.1.1
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: python-multipart>=0.0.32
+Requires-Dist: signxml>=4.4.0
+Requires-Dist: uvicorn>=0.49.0
+Requires-Dist: zeep>=4.3.2
+Description-Content-Type: text/markdown
+
+# openUBL
+
+[![PyPI](https://img.shields.io/pypi/v/openubl)](https://pypi.org/project/openubl/)
+[![npm](https://img.shields.io/npm/v/@openubl/sdk)](https://www.npmjs.com/package/@openubl/sdk)
+
+**Genera, firma y valida documentos electrónicos UBL 2.1 para SUNAT (Perú) — sin complicaciones.**
+
+openUBL es una biblioteca Python con API REST incluida. Genera XML válido para facturas, notas de crédito, notas de débito, comunicaciones de baja, resúmenes diarios, percepciones y retenciones. Firma digitalmente con certificados XAdES-EPES y valida contra las reglas SUNAT antes de enviar.
+
+## ¿Por qué openUBL?
+
+- **Sin dependencias externas** — todo en Python. No necesitas servicios de terceros para generar XML.
+- **API REST lista para usar** — levantas FastAPI y generas documentos vía HTTP.
+- **SDK TypeScript** — tipos generados desde OpenAPI, con autocompletado completo.
+- **Firma digital integrada** — firma con certificado PEM sin herramientas externas.
+- **Validación SUNAT** — detecta errores antes del envío, no después.
+- **Documentación completa** — guías paso a paso en [https://darvin2c.github.io/openUBL](https://darvin2c.github.io/openUBL)
+
+## Instalación rápida
+
+### Python
+
+```bash
+pip install openubl
+```
+
+```python
+from openubl.models import Invoice, Proveedor, Cliente, DocumentoVentaDetalle
+
+invoice = Invoice(
+    serie="F001",
+    numero=1,
+    proveedor=Proveedor(ruc="20100066603", razonSocial="Softgreen S.A.C."),
+    cliente=Cliente(nombre="Carlos", numeroDocumentoIdentidad="12121212121", tipoDocumentoIdentidad="6"),
+    detalles=[DocumentoVentaDetalle(descripcion="Item", cantidad=10, precio=100)],
+)
+
+xml = invoice.to_xml()
+print(xml)  # XML UBL 2.1 listo para firmar
+```
+
+### TypeScript / JavaScript
+
+```bash
+npm install @openubl/sdk
+```
+
+```typescript
+import { client, type Invoice } from "@openubl/sdk";
+
+const invoice: Invoice = {
+  serie: "F001",
+  numero: 1,
+  proveedor: { ruc: "20100066603", razonSocial: "Softgreen S.A.C." },
+  cliente: { nombre: "Carlos", numeroDocumentoIdentidad: "12121212121", tipoDocumentoIdentidad: "6" },
+  detalles: [{ descripcion: "Item", cantidad: 10, precio: 100 }],
+};
+
+const { data } = await client.POST("/api/v1/invoice/create", { body: invoice });
+console.log(data?.xml); // XML UBL 2.1 generado
+```
+
+## Levantar la API REST
+
+```bash
+uv run uvicorn openubl.main:app --reload
+```
+
+Abre [http://localhost:8000/docs](http://localhost:8000/docs) para Swagger UI interactivo.
+
+## Documentos soportados
+
+| Tipo | Código SUNAT | Endpoint |
+|------|-------------|----------|
+| Factura | 01 | `POST /api/v1/invoice/create` |
+| Boleta | 03 | `POST /api/v1/invoice/create` |
+| Nota de Crédito | 07 | `POST /api/v1/credit-note/create` |
+| Nota de Débito | 08 | `POST /api/v1/debit-note/create` |
+| Comunicación de Baja | RA | `POST /api/v1/voided-documents/create` |
+| Resumen Diario | RC | `POST /api/v1/summary-documents/create` |
+| Percepción | 40 | `POST /api/v1/perception/create` |
+| Retención | 20 | `POST /api/v1/retention/create` |
+
+## Validación de versión
+
+Verifica que tu SDK y la API compartan la misma versión:
+
+```python
+from openubl.version import check_api_version
+
+result = check_api_version("http://localhost:8000")
+assert result["ok"], f"Desfase: SDK {result['sdk_version']} vs API {result['api_version']}"
+```
+
+```typescript
+import { checkApiVersion } from "@openubl/sdk";
+
+const result = await checkApiVersion("http://localhost:8000");
+if (!result.ok) throw new Error(`Desfase: SDK ${result.sdkVersion} vs API ${result.apiVersion}`);
+```
+
+## Documentación
+
+- [Documentación completa](https://darvin2c.github.io/openUBL)
+- [Guía de Python SDK](https://darvin2c.github.io/openUBL/sdk/python)
+- [Guía de TypeScript SDK](https://darvin2c.github.io/openUBL/sdk/typescript)
+- [Referencia de API](https://darvin2c.github.io/openUBL/api/referencia)
+
+## Contribuir
+
+Consulta `AGENTS.md` para el contexto técnico completo del proyecto.
+
+## Licencia
+
+MIT © openUBL
+# Test release flow v2
+
+
+
+
+
+

openubl-0.1.3/README.md

@@ -0,0 +1,122 @@
+# openUBL
+
+[![PyPI](https://img.shields.io/pypi/v/openubl)](https://pypi.org/project/openubl/)
+[![npm](https://img.shields.io/npm/v/@openubl/sdk)](https://www.npmjs.com/package/@openubl/sdk)
+
+**Genera, firma y valida documentos electrónicos UBL 2.1 para SUNAT (Perú) — sin complicaciones.**
+
+openUBL es una biblioteca Python con API REST incluida. Genera XML válido para facturas, notas de crédito, notas de débito, comunicaciones de baja, resúmenes diarios, percepciones y retenciones. Firma digitalmente con certificados XAdES-EPES y valida contra las reglas SUNAT antes de enviar.
+
+## ¿Por qué openUBL?
+
+- **Sin dependencias externas** — todo en Python. No necesitas servicios de terceros para generar XML.
+- **API REST lista para usar** — levantas FastAPI y generas documentos vía HTTP.
+- **SDK TypeScript** — tipos generados desde OpenAPI, con autocompletado completo.
+- **Firma digital integrada** — firma con certificado PEM sin herramientas externas.
+- **Validación SUNAT** — detecta errores antes del envío, no después.
+- **Documentación completa** — guías paso a paso en [https://darvin2c.github.io/openUBL](https://darvin2c.github.io/openUBL)
+
+## Instalación rápida
+
+### Python
+
+```bash
+pip install openubl
+```
+
+```python
+from openubl.models import Invoice, Proveedor, Cliente, DocumentoVentaDetalle
+
+invoice = Invoice(
+    serie="F001",
+    numero=1,
+    proveedor=Proveedor(ruc="20100066603", razonSocial="Softgreen S.A.C."),
+    cliente=Cliente(nombre="Carlos", numeroDocumentoIdentidad="12121212121", tipoDocumentoIdentidad="6"),
+    detalles=[DocumentoVentaDetalle(descripcion="Item", cantidad=10, precio=100)],
+)
+
+xml = invoice.to_xml()
+print(xml)  # XML UBL 2.1 listo para firmar
+```
+
+### TypeScript / JavaScript
+
+```bash
+npm install @openubl/sdk
+```
+
+```typescript
+import { client, type Invoice } from "@openubl/sdk";
+
+const invoice: Invoice = {
+  serie: "F001",
+  numero: 1,
+  proveedor: { ruc: "20100066603", razonSocial: "Softgreen S.A.C." },
+  cliente: { nombre: "Carlos", numeroDocumentoIdentidad: "12121212121", tipoDocumentoIdentidad: "6" },
+  detalles: [{ descripcion: "Item", cantidad: 10, precio: 100 }],
+};
+
+const { data } = await client.POST("/api/v1/invoice/create", { body: invoice });
+console.log(data?.xml); // XML UBL 2.1 generado
+```
+
+## Levantar la API REST
+
+```bash
+uv run uvicorn openubl.main:app --reload
+```
+
+Abre [http://localhost:8000/docs](http://localhost:8000/docs) para Swagger UI interactivo.
+
+## Documentos soportados
+
+| Tipo | Código SUNAT | Endpoint |
+|------|-------------|----------|
+| Factura | 01 | `POST /api/v1/invoice/create` |
+| Boleta | 03 | `POST /api/v1/invoice/create` |
+| Nota de Crédito | 07 | `POST /api/v1/credit-note/create` |
+| Nota de Débito | 08 | `POST /api/v1/debit-note/create` |
+| Comunicación de Baja | RA | `POST /api/v1/voided-documents/create` |
+| Resumen Diario | RC | `POST /api/v1/summary-documents/create` |
+| Percepción | 40 | `POST /api/v1/perception/create` |
+| Retención | 20 | `POST /api/v1/retention/create` |
+
+## Validación de versión
+
+Verifica que tu SDK y la API compartan la misma versión:
+
+```python
+from openubl.version import check_api_version
+
+result = check_api_version("http://localhost:8000")
+assert result["ok"], f"Desfase: SDK {result['sdk_version']} vs API {result['api_version']}"
+```
+
+```typescript
+import { checkApiVersion } from "@openubl/sdk";
+
+const result = await checkApiVersion("http://localhost:8000");
+if (!result.ok) throw new Error(`Desfase: SDK ${result.sdkVersion} vs API ${result.apiVersion}`);
+```
+
+## Documentación
+
+- [Documentación completa](https://darvin2c.github.io/openUBL)
+- [Guía de Python SDK](https://darvin2c.github.io/openUBL/sdk/python)
+- [Guía de TypeScript SDK](https://darvin2c.github.io/openUBL/sdk/typescript)
+- [Referencia de API](https://darvin2c.github.io/openUBL/api/referencia)
+
+## Contribuir
+
+Consulta `AGENTS.md` para el contexto técnico completo del proyecto.
+
+## Licencia
+
+MIT © openUBL
+# Test release flow v2
+
+
+
+
+
+