# Roadmap — @wepos/sdk

Plan de evolución del SDK. Las fechas son orientativas; el orden refleja prioridad por valor
para integradores. Las sugerencias y PRs son bienvenidas en support@wecodecr.com.

---

## ✅ v1.0 — Núcleo de emisión (actual)

Superficie pública de integrador (autenticación por API key):

- **Facturas**: emitir FE/TE, Nota de Crédito (NC), Nota de Débito (ND), Factura de Exportación (FEE);
  consultar estado, listar, obtener XML firmado + respuesta de Hacienda.
- **`issueAndWait`**: emite y hace polling hasta `aceptado`/`rechazado`.
- **Clientes**: crear/actualizar, listar.
- **Catálogo**: productos, inventario por bodega, sucursales.
- **Referencia Hacienda**: validar CABYS, contribuyentes y exoneraciones.
- **DX**: idempotencia, reintentos con backoff (429/5xx), timeouts, errores tipados, ESM+CJS, tipos completos.

---

## ✅ v1.2 — Partner (backend fiscal embebido)

Superficie de plano de control para SaaS partner (partner key `wppk_…`, distinta de la key de tenant):

- `partner.tenants.create/list/get/update` — aprovisionar y gestionar tenants desde el SaaS.
- `partner.tenants.setCredentials/uploadCertificate` — credenciales ATV y certificado `.p12` **por ambiente** (STAGING/PRODUCTION).

## ✅ v1.3 — Migración de consecutivos (Partner)

- `partner.tenants.getConsecutives/setConsecutives` — fijar el consecutivo de arranque cuando un negocio **migra desde otro sistema** (ej. venía en la FE 400 → la próxima sale 401). Por ambiente, **atómico** (todo el lote o nada) y **monótono** (el nuevo valor debe ser ≥ el actual).

## ✅ v1.4 — Data keys por ambiente (Partner)

- `partner.tenants.issueKey(tenantId, { environment? })` — emite una data key (`wpk_…`) para un tenant EXISTENTE, por ambiente. Resuelve mover un tenant entre sandbox y producción sin recrearlo (el ambiente lo manda la data key, estilo Stripe, así que un tenant puede tener keys de ambos).
- `partner.tenants.listKeys(tenantId)` / `revokeKey(tenantId, keyId)` — listar (solo metadatos) y revocar.

## 🔜 Webhooks y eventos

El backend ya firma las entregas estilo Stripe (`x-wepos-signature: t=…,v1=…`, HMAC-SHA256 de
`${timestamp}.${body}`). El SDK expondrá la verificación, que hoy cada integrador debe implementar a mano.

- `WeposClient.webhooks.verify(rawBody, signatureHeader, secret, { toleranceSec })` → valida firma y frescura (anti-replay).
- Tipos de eventos fiscales (`document.accepted`, `document.rejected`, `document.error`, …) con payload tipado.
- Helpers de framework: handler para **Next.js Route Handler** y middleware **Express**.
- Gestión de endpoints de webhook vía API (crear/listar/rotar secreto, reintentar entregas).

## 🔜 Listados y paginación

- Auto-paginación / async iterators (`for await (const inv of wepos.invoices.iterate())`).
- Filtros adicionales en listados: rango de fechas, estado de Hacienda, sucursal, cliente.
- Helpers de exportación (CSV/streaming) para grandes volúmenes.

## 🔜 Más recursos de negocio

Requiere exponer estos dominios como **scopes de API key** en el backend (hoy varios viven tras token de dispositivo):

- **Ventas POS**: crear ventas, sesiones de caja (abrir/cerrar), devoluciones, impresión.
- **Cuentas por cobrar / pagar**: listar, detalle, registrar pagos, estados de cuenta, resumen y aging.
- **Reportes**: ventas, impuestos, reporte Z, libros de ventas/compras, conciliación, exportación contable.
- **Catálogo avanzado**: listas de precios, promociones, combos.
- **Compras (procurement)**: proveedores, órdenes de compra, recepciones, facturas de proveedor, bandeja de recibidos.

## 🔭 v2.0 — Apps móviles y desktop

- **Auth de dispositivos**: flujo `auth/login` + `auth/refresh` con rotación y refresco automático del access token.
- **Change feed / sync**: consumo de `sync/events` con cursores para apps **offline-first**.
- **Subida de archivos**: logos de empresa e imágenes de producto.
- **Modo contingencia**: helpers para emisión offline y posterior sincronización.

## 🌎 Más allá

- **SDK de PHP** y **SDK de Python** generados desde el OpenAPI (mercado CR: WooCommerce/Laravel, ERPs).
- **CLI `wepos`**: emitir y consultar comprobantes desde la terminal / scripts de CI.
- **Fixtures de prueba** y un modo `mock` para tests de integradores sin tocar Hacienda.
- **OpenAPI completo**: cerrar los esquemas request/response de todos los endpoints para habilitar la generación multi-lenguaje.

---

## Principios de diseño

1. **Cero dependencias en runtime** — el SDK no debe arrastrar árbol de dependencias al proyecto del integrador.
2. **Tipado primero** — todo método y payload tipado; los tipos reflejan el OpenAPI.
3. **Seguro por defecto** — fail-closed en validaciones, idempotencia en escrituras, reintentos solo en errores idempotentes.
4. **DX sobre completitud** — preferimos un método ergonómico (`issueAndWait`) a exponer el HTTP crudo.
5. **SemVer estricto** — breaking changes solo en major.