veriko 0.4.1__tar.gz

veriko-0.4.1/.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Estilo y tipos
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Instalar el paquete y sus herramientas
+        run: pip install -e ".[dev]"
+
+      - name: ruff check
+        run: ruff check .
+
+      - name: ruff format
+        run: ruff format --check .
+
+      - name: mypy
+        run: mypy
+
+      - name: Los ejemplos compilan
+        run: python -m compileall -q examples
+
+  test:
+    name: Pruebas (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Instalar el paquete y sus herramientas
+        run: pip install -e ".[dev]"
+
+      - name: pytest
+        run: pytest
+
+  build:
+    name: El paquete se construye
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Construir la distribución
+        run: |
+          pip install build twine
+          python -m build
+          twine check dist/*

veriko-0.4.1/.github/workflows/publish.yml

@@ -0,0 +1,129 @@
+name: Publicar en PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Pruebas (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - run: pip install -e ".[dev]"
+      - run: pytest
+
+  build:
+    name: Verificar y construir
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Verificar la etiqueta
+        shell: bash
+        run: |
+          version="$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")"
+          if [ "$GITHUB_REF_NAME" != "v$version" ]; then
+            echo "La etiqueta $GITHUB_REF_NAME no coincide con la versión $version." >&2
+            exit 1
+          fi
+          git fetch origin main
+          git merge-base --is-ancestor "$(git rev-list -n 1 "$GITHUB_REF_NAME")" origin/main
+
+      - name: Instalar herramientas
+        run: pip install -e ".[dev]" build twine
+
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy
+      - run: python -m compileall -q examples
+
+      - name: Construir y revisar la distribución
+        run: |
+          python -m build
+          twine check dist/*
+          python -m venv /tmp/veriko-package
+          /tmp/veriko-package/bin/pip install dist/*.whl
+          /tmp/veriko-package/bin/python -c "from veriko import Veriko; assert Veriko"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-package
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publicar
+    needs: [test, build]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/veriko
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-package
+          path: dist/
+
+      - name: Publicar en PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+
+  release:
+    name: Publicar las notas
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Extraer la entrada del changelog
+        env:
+          VERSION: ${{ github.ref_name }}
+        shell: bash
+        run: |
+          python - <<'PY'
+          import os
+          import re
+          from pathlib import Path
+
+          version = os.environ['VERSION'].removeprefix('v')
+          changelog = Path('CHANGELOG.md').read_text(encoding='utf-8')
+          match = re.search(
+              rf'^## \[{re.escape(version)}\][^\n]*\n(?P<body>.*?)(?=^## \[|\Z)',
+              changelog,
+              flags=re.MULTILINE | re.DOTALL,
+          )
+          if match is None:
+              raise SystemExit(f'No existe una entrada para {version} en CHANGELOG.md')
+          Path('release-notes.md').write_text(match.group('body').strip() + '\n', encoding='utf-8')
+          PY
+
+      - name: Crear la release de GitHub
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release create "$GITHUB_REF_NAME" --verify-tag --title "$GITHUB_REF_NAME" --notes-file release-notes.md

veriko-0.4.1/.github/workflows/sync-public-spec.yml

@@ -0,0 +1,20 @@
+name: Sincronizar el spec público
+
+on:
+  schedule:
+    - cron: '32 8 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  sync:
+    uses: veriko-mx-labs/.github/.github/workflows/sync-public-spec.yml@main
+    with:
+      regenerate_command: 'true'
+      auto_merge: true
+    secrets:
+      app_id: ${{ secrets.VERIKO_LABS_APP_ID }}
+      app_private_key: ${{ secrets.VERIKO_LABS_PRIVATE_KEY }}

veriko-0.4.1/.gitignore

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

veriko-0.4.1/CHANGELOG.md

@@ -0,0 +1,184 @@
+# Registro de cambios
+
+Formato de [Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/);
+versiones según [SemVer](https://semver.org/lang/es/).
+
+## [No publicado]
+
+## [0.4.1] — 2026-09-19
+
+Primera versión publicada en PyPI. No cambia la superficie del SDK respecto de
+`0.4.0`.
+
+Los cambios del producto se documentan en el
+[changelog de la API](https://docs.veriko.mx/es/changelog).
+
+## [0.4.0] — 2026-09-18
+
+La superficie pasa de 48 operaciones a 49: `beneficiaries` gana la cancelación de
+una importación, y con ella el SDK cubre todas las operaciones de máquina a máquina de
+sus cinco familias.
+
+### Añadido
+
+- `beneficiaries.import_cancel()`: cancela una importación que todavía no se
+  confirmó (`DELETE /beneficiaries/imports/{id}`).
+
+### Cambiado
+
+- `test_operations.py` exige que las cinco familias no traigan operaciones de máquina a
+  máquina sin método, en lugar de admitir una excepción.
+
+## [0.3.1] — 2026-09-18
+
+Las familias `validations`, `webhooks` y `catalog` pasan a seguir el spec público. Las pruebas
+de 0.2.0 comprobaban el SDK contra respuestas escritas a mano que no coincidían con el spec, así que
+pasaban aunque el código enviara o leyera campos que la API no tiene. Varias formas de lo que
+devuelve el SDK cambian; el paquete todavía no está publicado en PyPI.
+
+### Corregido
+
+- `set_retry_policy()` envía el cuerpo envuelto en `retry_policy`, como exige el spec.
+  Antes lo mandaba sin envolver.
+- `set_retry_policy()` y `cancel_retries()` devuelven el estado del ciclo (`RetryState`) y no una
+  validación vacía: la respuesta del spec trae sólo `retry_state`.
+- `ValidationSummary` deja de tener `has_cep`, `links` y `completed_at`, que un elemento de listado
+  no trae, y gana los campos que sí trae (`bank_name`, `amount`, `tracking_key`, `retry_state`...).
+- `RetryAttempt` lee los campos del spec: `attempt_number`, `dispatched_at`, `new_status`...
+- `Bank` gana `aliases` y pierde `short_name`, que el spec no declara.
+- `list(playground=True)` y `with_deleted=True` viajaban como `True`; ahora `playground` envía `1` y
+  `with_deleted` envía `1` o `0`. El transporte ya no codifica ningún booleano como `True`.
+- `webhooks.deliveries()` y `export_deliveries()` descartaban `status` y `event_type` cuando se
+  pasaba un endpoint. Ahora consultan el listado global con `endpoint_id`.
+- Una lectura condicional que recibe `304` levanta `APIError` con `status=304`, como decía la
+  documentación. Antes `get()` devolvía una validación vacía y `banks()` una lista vacía.
+- `webhooks.update(events=[])` levanta `events_required` en lugar de descartar el cambio.
+- `validations.image()` propone un nombre con extensión cuando la respuesta no trae
+  `Content-Disposition`.
+
+### Cambiado
+
+- `stats()`, `bin_lookup()`, `banxico_status()`, `banxico_timeseries()` y `send_cep_to_telegram()`
+  devuelven los atributos del recurso, como ya hace `client.usage`: `stats["total"]`.
+- `catalog.banks()` devuelve un `BankList`, una lista de `Bank` con el `ETag` en `etag`.
+- `RetryState` gana `max_retries`, `interval_seconds` y `outcomes`.
+- `WebhookEndpoint` gana `description`, `secret_hint`, `last_delivery_at` y `updated_at`;
+  `WebhookDelivery` gana `endpoint_id`, `endpoint_url`, `validation_id`, `attempt`,
+  `response_body` y `next_retry_at`.
+
+### Añadido
+
+- `description` en `webhooks.create()` y `webhooks.update()`.
+- `spec/openapi.yaml`, copia del spec público, y tres pruebas que lo usan:
+  `test_operations.py` contrasta cada operación con el spec y exige que sea de máquina a
+  máquina; `test_models_follow_spec.py` comprueba que los campos de cada modelo existan en él;
+  `test_spec_public.py` vigila que la copia no sea el bundle interno.
+- Las grabaciones de las familias `validations`, `webhooks` y `catalog` se recortan de los
+  ejemplos del spec público.
+
+## [0.3.0] — 2026-09-18
+
+La superficie pasa de 27 operaciones a 48: se suman las familias
+`beneficiaries` y `usage`. Es la segunda y última tanda del alcance fijado.
+
+### Añadido
+
+- `client.beneficiaries`: registrar, listar, cambiar y archivar cuentas
+  beneficiarias; validación estructural de una cuenta sin gastar cuota
+  (`validate_account`); resolución de una cuenta en la lista propia (`lookup`);
+  exportación en CSV y XLSX; y la importación masiva como ciclo
+  (`import_template`, `import_start`, `import_status`, `import_preview`,
+  `import_edit_row`, `import_remove_row`, `import_commit` e `import_wait`).
+- `client.usage`: cuota del plan (`summary`), historial mensual (`history`),
+  desglose por operación (`breakdown`), límites de tasa (`limits`), mapa de
+  calor (`heatmap`), métricas de la API (`api_usage`) y su exportación
+  (`export`).
+- Los tipos `Beneficiary`, `BeneficiaryLookup`, `AccountValidation`,
+  `BeneficiaryImportJob`, `BeneficiaryImportRow` y `UsageSummary`.
+- `BeneficiaryImportJob.is_settled`: la condición que espera `import_wait()`
+  (`preview_ready` o un estado final).
+- Subida de archivos `multipart/form-data` en el transporte, sin dependencias
+  de runtime.
+
+### Cambiado
+
+- El transporte codifica los valores de consulta que son listas como
+  parámetros repetidos, para el filtro `buckets` de la vista previa.
+- El arnés de pruebas entiende `PATCH`, que usa la corrección de filas.
+
+### Pendiente para versiones siguientes
+
+- Nada dentro del alcance fijado. Quedan fuera de propósito finanzas, métricas
+  propias, catálogo de planes, suscripción y el resumen del panel.
+
+## [0.2.0] — 2026-09-18
+
+La superficie pasa de 3 operaciones a 27: las familias `validations`, `webhooks`
+y `catalog` completas.
+
+### Añadido
+
+- `client.validations`: validación por imagen (`validate_ocr`), modo asíncrono
+  (`enqueue`, `enqueue_ocr`) con sondeo por `ETag` (`wait_for`), listado con
+  paginación (`list`, `iter`), estadísticas, exportación en CSV y XLSX, imagen
+  del comprobante, intentos de reintento, cambio de la política de reintentos,
+  cancelación, retirada del historial y envío del comprobante a Telegram.
+- `client.webhooks`: registrar, listar, cambiar y retirar endpoints; evento de
+  prueba; rotación del secreto; historial de entregas con paginación y su
+  exportación.
+- `client.catalog`: catálogo de bancos SPEI, banco emisor de una tarjeta y
+  estado del servicio de Banxico con su serie temporal.
+- `Page` y los iteradores `iter*`, que piden la página siguiente sólo cuando la
+  anterior se agota.
+- `Validation.is_settled`: distingue un veredicto firme de uno terminal que
+  todavía puede cambiar porque hay reintentos en marcha. Es lo que espera
+  `wait_for()`.
+- Los tipos `ValidationSummary`, `WebhookEndpoint`, `WebhookDelivery`,
+  `WebhookTestResult`, `RetryAttempt`, `Bank` y `Document`.
+
+### Cambiado
+
+- `validate_transfer()`, `get_validation()` y `get_cep()` siguen en la raíz del
+  cliente y se comportan igual: ahora delegan en la familia correspondiente.
+- `Validation` gana el campo `etag`, que `get()` rellena con la cabecera de la
+  respuesta.
+
+### Pendiente para versiones siguientes
+
+- Beneficiarios, con su importación masiva.
+- Métricas de consumo y límites de tasa.
+
+## [0.1.0] — 2026-09-18
+
+Primera versión del SDK oficial de Python.
+
+### Añadido
+
+- `Veriko.validate_transfer()`: valida una transferencia SPEI contra el CEP de
+  Banxico (`POST /v1/validate`), con la política de reintentos de la API
+  (`retry_policy`) y la cabecera `Idempotency-Key`.
+- `Veriko.get_validation()`: lee una validación por su identificador, con el
+  estado del ciclo de reintentos.
+- `Veriko.get_cep()`: descarga el comprobante oficial en XML o en PDF.
+- `verify_webhook()` y `parse_webhook()`: verificación HMAC-SHA256 de la firma
+  de una entrega, con comparación en tiempo constante.
+- Reintentos automáticos de los `5xx`, el `408` y el `429`, con espera
+  exponencial y respeto del `Retry-After` de la respuesta.
+- Jerarquía de excepciones por estado HTTP, con el `code` de la API, el arreglo
+  completo de `errors` y el `request_id`.
+- Tipado completo (`py.typed`), sin dependencias de runtime. Python 3.9 o
+  superior.
+
+### Pendiente para versiones siguientes
+
+- Modo asíncrono (`?async=1`) y sondeo con `ETag`.
+- Validación por OCR de una imagen de comprobante.
+- Beneficiarios, importación masiva y finanzas.
+
+[No publicado]: https://github.com/veriko-mx-labs/veriko-python/compare/v0.4.1...HEAD
+[0.4.1]: https://github.com/veriko-mx-labs/veriko-python/releases/tag/v0.4.1
+[0.4.0]: https://github.com/veriko-mx-labs/veriko-python/releases/tag/v0.4.0
+[0.3.1]: https://github.com/veriko-mx-labs/veriko-python/releases/tag/v0.3.1
+[0.3.0]: https://github.com/veriko-mx-labs/veriko-python/releases/tag/v0.3.0
+[0.2.0]: https://github.com/veriko-mx-labs/veriko-python/releases/tag/v0.2.0
+[0.1.0]: https://github.com/veriko-mx-labs/veriko-python/releases/tag/v0.1.0

veriko-0.4.1/LICENSE

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