mercadopublico 0.0.2 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,29 @@
+# mercadopublico
+
+## 0.1.0
+
+### Minor Changes
+
+- 1b30195: Primera versión pública (0.1).
+  
+  - **Cliente tipado** para la API v1 (licitaciones, órdenes de compra, `BuscarProveedor` y `BuscarComprador`) y la v2 de Compra Ágil (listado paginado y detalle), con errores tipados (`MercadoPublicoError`) y validación de entradas antes de gastar consultas.
+  - **Un solo modelo, `Proceso`,** para v1, v2 y OCDS:
+    - fechas ISO con offset de Santiago;
+    - montos `{ valor, moneda, clp, fechaValor, fuente }` convertidos con el valor del día del documento: mindicador.cl, luego el Banco Central y al final la paridad mensual de ChileCompra.
+  - **Resiliencia:**
+    - cola serial con ritmo adaptativo ante el 10500;
+    - reintentos con presupuesto;
+    - circuit breaker por fuente (`mp.salud()`);
+    - cancelación con `AbortSignal`;
+    - eventos de observabilidad (`alEvento`);
+    - cuota diaria en `mp.cuota`.
+  - **`mp.sync.planificar` y `mp.sync.ejecutar`:**
+    - sincronización incremental con costo estimado antes de empezar;
+    - cursores que nunca adelantan a los datos y pendientes con tope;
+    - stores en memoria y en archivo, con lock y escritura atómica.
+  - **Avisos cuando la API cambia de forma** (campo nuevo o faltante, tipo distinto, valor desconocido).
+  - **Lector OCDS en streaming** (`leerOcds`) para el histórico de datos abiertos.
+  - **Tablas de códigos** con las contradicciones de la documentación oficial corregidas.
+  - **Datos personales de funcionarios** marcados en `personales`. `ocultarPersonales` los tapa, junto con correos y teléfonos en texto libre.
+  - **CLI `mercadopublico`** con salida JSON, CSV y tabla, `sync`, `radar` y `ocds`. Oculta datos personales por defecto.
+  - **`mercadopublico/radar`:** `decidir`, `priorizar`, `precioSugerido`, `rangoDePrecio`, `proximasCompras`, `competidores` y `calibrar`, con fórmulas explícitas.

package/LICENSE

@@ -1,21 +1,133 @@
-MIT License
-
-Copyright (c) 2026 keroke.ro
-
-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.
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree
+to them as both strict obligations and conditions to all
+your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the
+software to do everything you might do with the software
+that would otherwise infringe the licensor's copyright
+in it for any permitted purpose.  However, you may
+only distribute the software according to [Distribution
+License](#distribution-license) and make changes or new works
+based on the software according to [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license
+to distribute copies of the software.  Your license
+to distribute covers distributing the software with
+changes and new works permitted by [Changes and New Works
+License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of
+the software from you also gets a copy of these terms or the
+URL for them above, as well as copies of any plain-text lines
+beginning with `Required Notice:` that the licensor provided
+with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to
+make changes and new works based on the software for any
+permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that
+covers patent claims the licensor can license, or becomes able
+to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for
+the benefit of public knowledge, personal study, private
+entertainment, hobby projects, amateur pursuits, or religious
+observance, without any anticipated commercial application,
+is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution,
+public research organization, public safety or health
+organization, environmental protection organization,
+or government institution is use for a permitted purpose
+regardless of the source of funding or obligations resulting
+from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the
+law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of
+your licenses to anyone else, or prevent the licensor from
+granting licenses to anyone else.  These terms do not imply
+any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If
+your company makes such a claim, your patent license ends
+immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have
+violated any of these terms, or done anything with the software
+not covered by your licenses, your licenses can nonetheless
+continue if you come into full compliance with these terms,
+and take practical steps to correct past violations, within
+32 days of receiving notice.  Otherwise, all your licenses
+end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without
+any warranty or condition, and the licensor will not be liable
+to you for any damages arising out of these terms or the use
+or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these
+terms, and the **software** is the software the licensor makes
+available under these terms.
+
+**You** refers to the individual or entity agreeing to these
+terms.
+
+**Your company** is any legal entity, sole proprietorship,
+or other kind of organization that you work for, plus all
+organizations that have control over, are under the control of,
+or are under common control with that organization.  **Control**
+means ownership of substantially all the assets of an entity,
+or the power to direct its management and policies by vote,
+contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the
+software under these terms.
+
+**Use** means anything you do with the software requiring one
+of your licenses.
+
+Required Notice: Copyright KeroKero (https://kerokero.cl)

package/README.md

@@ -1,20 +1,167 @@
-# mercadopublico
+![mercadopublico: la API de Mercado Público, bien usada. SDK en TypeScript por KeroKero.](https://unpkg.com/mercadopublico/docs/assets/readme/portada.png)
 
-SDK en TypeScript para la [API de Mercado Público](https://www.chilecompra.cl/api/) de ChileCompra.
+[![ci](https://img.shields.io/github/actions/workflow/status/keroke-ro/mercadopublico/ci.yml?branch=main&label=ci&style=flat-square&labelColor=171A17)](https://github.com/keroke-ro/mercadopublico/actions/workflows/ci.yml)
+[![contrato](https://img.shields.io/github/actions/workflow/status/keroke-ro/mercadopublico/contrato.yml?branch=main&label=contrato&style=flat-square&labelColor=171A17)](https://github.com/keroke-ro/mercadopublico/actions/workflows/contrato.yml)
+[![npm](https://img.shields.io/npm/v/mercadopublico?color=2F6A3B&style=flat-square&labelColor=171A17)](https://www.npmjs.com/package/mercadopublico)
+[![dependencias](https://img.shields.io/badge/dependencias_en_runtime-0-2F6A3B?style=flat-square&labelColor=171A17)](package.json)
+[![licencia](https://img.shields.io/badge/licencia-PolyForm_Noncommercial-2F6A3B?style=flat-square&labelColor=171A17)](LICENSE)
 
-> En construcción (v0.1). No oficial: no está afiliado a la Dirección ChileCompra.
+SDK en TypeScript para la [API de Mercado Público](https://www.chilecompra.cl/api/) de ChileCompra. Junta la API v1 (licitaciones, órdenes de compra y empresas), la v2 de Compra Ágil y las descargas OCDS en un solo modelo, `Proceso`, para que tu código no dependa de cuál de las tres trajo el dato. Se hace cargo de lo que cuesta usar bien la API: manda las consultas de a una para no gatillar el error 10500, reintenta solo cuando sirve, lleva la cuenta de las 10.000 consultas diarias del ticket, convierte los montos a pesos con el valor del día del documento y oculta los datos personales de funcionarios en la CLI. No tiene dependencias en runtime.
 
-## Objetivo
+![Las tres APIs (v1, Compra Ágil y OCDS) se traducen a un solo tipo, Proceso: con tipo y origen, montos en pesos al valor del día, fechas ISO con offset de Santiago, datos de funcionarios aparte y lo desconocido en raw.](https://unpkg.com/mercadopublico/docs/assets/readme/modelo.png)
 
-- Cliente tipado para licitaciones, órdenes de compra, empresas y Compra Ágil, con los códigos como enums y errores tipados.
-- Control de cuota (10.000 consultas diarias por ticket), cola serial y reintentos solo cuando corresponde (10500, 429, 5xx).
-- Normalización de montos (CLP, UF, UTM, USD) y fechas en America/Santiago.
-- Lector del histórico OCDS de datos abiertos de ChileCompra.
+> No oficial: no está afiliado a la Dirección ChileCompra.
+
+## Instalación
+
+```sh
+npm install mercadopublico
+```
+
+Requiere Node 20 o superior (usa `fetch` nativo). Se publica como ESM y CJS. Necesitas un ticket de la API: se pide con Clave Única en [chilecompra.cl/api](https://www.chilecompra.cl/api/) y llega por correo.
+
+## En 30 segundos
+
+```ts
+import { MercadoPublico } from "mercadopublico";
+
+const mp = new MercadoPublico({ ticket: process.env.MP_TICKET! });
+
+const activas = await mp.licitaciones.activas(); // 1 consulta
+console.log(activas.length, "licitaciones publicadas hoy");
+
+const lic = await mp.licitaciones.porCodigo("1509-5-L114"); // 1 consulta; null si no existe
+if (lic) {
+  console.log(lic.estado, lic.fechas.cierre); // "publicada" "2026-10-20T15:00:00-03:00"
+  console.log(lic.monto); // { valor: 1200, moneda: "CLF", clp: 47_000_000, fechaValor: "2026-10-01", fuente: "mindicador.cl" }
+}
+
+// Compra Ágil: pagina sola, 1 consulta por página de 50
+for await (const ca of mp.compraAgil.listar({ region: [13], estado: ["publicada"], q: "papel" })) {
+  console.log(ca.codigo, ca.nombre, ca.monto?.clp);
+}
+
+console.log(mp.cuota.toJSON()); // { dia, usadas, limite: 10000, restante, reinicia }
+```
+
+## Cuota
+
+El ticket da 10.000 consultas por día calendario. Si mandas dos a la vez, la API responde 10500; si se te acaban, 429. El SDK:
+
+- **Pone todas las consultas en una cola serial.** Nunca hay dos en vuelo, aunque llames en paralelo.
+- **Reintenta solo lo que tiene arreglo:** 10500, 5xx y cortes de red, con backoff exponencial y jitter (4 reintentos, base 1 s). Nunca reintenta un ticket inválido, un 404, parámetros malos ni un 429.
+- **Lleva la cuenta en `mp.cuota`** (`usadas`, `restante`, `limite`, `reinicia`). Cada intento cuenta, también los reintentos. La API no informa cuánto queda, así que es la cuenta de este proceso: si quieres que sobreviva entre ejecuciones, guarda `mp.cuota.toJSON()` y pásalo como `cuota` al crear el cliente. La CLI ya lo hace.
+- **Falla antes de gastar** con `cuota_insuficiente` si una operación no cabe en lo que queda del día.
+- **Planifica los sync.** `mp.sync.planificar()` dice cuántas consultas va a costar y si alcanzan hoy, antes de pedir un solo detalle:
+
+```ts
+const plan = await mp.sync.planificar({ desde: "2026-10-01", store });
+plan.consultas; // 1240
+plan.cabeHoy; // true
+await mp.sync.ejecutar(plan);
+```
+
+Detalle en [docs/sync.md](docs/sync.md).
+
+## Resiliencia
+
+La API falla seguido: rechaza con 10500 incluso consultas seriales (3 de cada 11 con 1 s de pausa) y a veces se cae entera. El SDK alarga la pausa sola ante cada 10500, pone un tope a los reintentos, deja de consultar una fuente caída por 60 s (circuit breaker) y acepta un `signal` en cada método. Un sync cortado en cualquier punto se reanuda sin huecos.
+
+```ts
+const mp = new MercadoPublico({
+  ticket: process.env.MP_TICKET!,
+  alEvento: (e) => console.error(JSON.stringify(e)), // consultas, reintentos, circuito, cuota, avisos de cambios en la API
+});
+mp.salud(); // { v1: { estado: "cerrado", fallas: 0, intervaloMs: 1000 }, v2: { … }, … }
+```
+
+![Cada falla y su respuesta: 10500, ritmo adaptativo; 5xx, timeout o red, reintentos con backoff y jitter; 5 caídas seguidas, circuito abierto 60 s; sync cortado, reanuda sin huecos; la API cambia, parsea igual y avisa; conversor caído, pasa al siguiente.](https://unpkg.com/mercadopublico/docs/assets/readme/resiliencia.png)
+
+Qué pasa en cada falla, en [docs/resiliencia.md](docs/resiliencia.md).
+
+## Datos personales
+
+La v1 trae nombre, RUT, correo y teléfono de funcionarios (`RutUsuario`, `NombreUsuario`, `EmailResponsablePago`, `FonoResponsableContrato`, etc.). El SDK los separa en `proceso.personales`, y:
+
+- **La CLI los oculta por defecto.** Para verlos: `--incluir-personales`.
+- **En código los recibes tal como vienen.** Antes de exportar o publicar, pasa cada proceso por `ocultarPersonales`, que deja `personales` en `null` y tapa esos campos dentro de `raw`:
+
+```ts
+import { ocultarPersonales } from "mercadopublico";
+
+const publicable = procesos.map(ocultarPersonales);
+```
+
+No se tapan el RUT ni la razón social de los proveedores: son datos de empresas, salvo cuando el proveedor es persona natural, y la API no lo indica. La Ley 21.719 de protección de datos personales empieza a regir en diciembre de 2026; si vas a publicar o cruzar estos datos, confirma el alcance con un abogado.
+
+## Radar
+
+`mercadopublico/radar` responde lo que se pregunta cada mañana un equipo que le vende al Estado: qué postular primero, a qué precio, contra quién compite y qué viene. Son fórmulas a la vista, sin machine learning: cada número trae su porqué en texto, y tu criterio (pesos, rubros, costos, vetos) entra en un `Perfil`.
+
+![El puntaje es una suma ponderada de seis factores. decidir lo pasa por reglas duras, umbrales (0,7 postular, 0,4 revisar), capacidad y orden por cierre.](https://unpkg.com/mercadopublico/docs/assets/readme/radar.png)
+
+```sh
+npx mercadopublico radar --perfil perfil.json --decisiones decisiones.json
+```
+
+Detalle en [docs/radar.md](docs/radar.md).
+
+## CLI
+
+```sh
+export MP_TICKET=...
+npx mercadopublico licitacion 1509-5-L114
+npx mercadopublico licitaciones --dia 2026-10-01 --estado adjudicada --formato csv > adjudicadas.csv
+npx mercadopublico compra-agil --region 13 --estado publicada --q papel --max 50
+npx mercadopublico ocds 2026 --max 10           # no pide ticket
+npx mercadopublico sync --desde 2026-10-01 --plan
+npx mercadopublico cuota
+```
+
+Salida en tabla si es una terminal y JSON si no; `--formato json|csv|tabla` para elegir. Referencia completa en [docs/cli.md](docs/cli.md).
+
+## Documentación
+
+- [Guía](docs/guia.md): cliente, licitaciones, órdenes de compra, empresas, Compra Ágil y errores.
+- [Modelo](docs/modelo.md): `Proceso`, `Monto`, fechas y conversores.
+- [Sync](docs/sync.md): plan, costo en consultas, cursores y stores.
+- [CLI](docs/cli.md)
+- [OCDS](docs/ocds.md): el histórico de datos abiertos, en streaming.
+- [Radar](docs/radar.md): `mercadopublico/radar` y `mercadopublico radar`: qué postular primero, a qué precio, contra quién y qué viene.
+- [Resiliencia](docs/resiliencia.md): qué hace el SDK cuando la API falla, eventos y `mp.salud()`.
+- [Testing](docs/testing.md): qué se prueba, dónde corre y cuántas consultas reales gasta.
+- [Contrato nocturno](docs/contrato.md)
+- [Notas de la API](docs/api-notes.md): lo que dice cada fuente oficial y dónde se contradicen.
+
+## Calidad
+
+Cada PR corre, en Node 20, 22 y 24, typecheck, tests unitarios, propiedades con fast-check, un corpus de 59 respuestas reales anonimizadas con snapshots y pruebas de caos contra un servidor local; además, cobertura con umbrales y el paquete tal como se publica, importado desde Node, Bun, Deno y un entorno tipo edge. Cada semana corren la prueba de mutación y un smoke contra la API real; cada noche, el [contrato](docs/contrato.md). Detalle en [docs/testing.md](docs/testing.md).
+
+## Estado
+
+Versión 0.x: la API pública todavía puede cambiar entre versiones menores (ver [CONTRIBUTING.md](CONTRIBUTING.md#versiones)).
+
+Probado con un ticket real desde el 2026-10-13: la v1 tiene fixtures grabados de la API (`test/fixtures/v1/*.real.json`) y un corpus de respuestas reales anonimizadas (ver [docs/testing.md](docs/testing.md#corpus-real-y-snapshots)). Los fixtures de la v2 y de OCDS siguen reconstruidos desde la documentación oficial y llevan la marca `"_fixture": "reconstruido…"`. Estas dudas siguen abiertas (detalle en [docs/api-notes.md](docs/api-notes.md)):
+
+- En qué zona horaria se reinicia la cuota (el SDK supone medianoche de Santiago) y si v1 y v2 comparten contador.
+- Si el servidor acepta la grafía correcta de dos filtros de estado de OC que la documentación escribe con errata (`recepcionaceptadacialmente`, `recepecionconformeincompleta`). El SDK manda la de la documentación.
+- Detalles de forma: si `Publico` en las rutas de Empresas distingue mayúsculas, si el filtro `region` de la v2 va separado por comas o repetido, y con qué status HTTP llega el error 10300.
+- Si las fechas OCDS con sufijo `Z` son UTC reales o la hora de Santiago etiquetada como UTC. El SDK las lee como hora de Santiago.
+- En Compra Ágil, `codigo_orden_compra` viene en `null` aunque la OC exista (el SDK usa `id_orden_compra`), y `seleccion.proveedor_seleccionado` está documentado pero no confirmado.
+- mindicador.cl no respondía al investigar; si falla, el conversor usa los valores diarios del Banco Central (sus páginas "Ver serie", no una API) y, si eso también falla, el promedio mensual oficial de ChileCompra.
 
 ## Fuente de los datos
 
 Los datos vienen de la Dirección ChileCompra (api.mercadopublico.cl). Si publicas datos obtenidos con esta librería, cita a ChileCompra como fuente.
 
+Esta librería no está afiliada a la Dirección ChileCompra ni cuenta con su respaldo.
+
 ## Licencia
 
-MIT © KeroKero
+[PolyForm Noncommercial 1.0.0](LICENSE): libre para uso no comercial (personal, investigación, educación, organizaciones sin fines de lucro e instituciones públicas). Para uso comercial, escríbenos a [KeroKero](https://kerokero.cl).
+
+Required Notice: Copyright KeroKero (https://kerokero.cl)
+
+---
+
+<img src="https://unpkg.com/mercadopublico/docs/assets/readme/kerokero.svg" width="18" height="18" alt=""> Hecho por [KeroKero](https://kerokero.cl): sistemas de decisión para tu operación.

package/dist/chunk-EZCMRQY6.js

@@ -0,0 +1,75 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/fecha.ts
+var ZONA = "America/Santiago";
+var partes = new Intl.DateTimeFormat("en-CA", {
+  timeZone: ZONA,
+  year: "numeric",
+  month: "2-digit",
+  day: "2-digit",
+  hour: "2-digit",
+  minute: "2-digit",
+  second: "2-digit",
+  hourCycle: "h23",
+  timeZoneName: "longOffset"
+});
+function piezas(d) {
+  const p = {};
+  for (const { type, value } of partes.formatToParts(d)) p[type] = value;
+  const gmt = p.timeZoneName === "GMT" ? "+00:00" : p.timeZoneName.slice(3);
+  const ms = (gmt[0] === "-" ? -1 : 1) * (Number(gmt.slice(1, 3)) * 3600 + Number(gmt.slice(4, 6)) * 60 + Number(gmt.slice(7, 9) || 0)) * 1e3;
+  return { dia: `${p.year}-${p.month}-${p.day}`, hora: `${p.hour}:${p.minute}:${p.second}`, off: gmt.slice(0, 6), ms };
+}
+function isoSantiago(d) {
+  const { dia, hora, off } = piezas(d);
+  return `${dia}T${hora}${off}`;
+}
+function diaSantiago(d = /* @__PURE__ */ new Date()) {
+  return piezas(d).dia;
+}
+var FORMA = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+function desdeHoraSantiago(texto) {
+  if (!FORMA.test(texto)) throw new RangeError(`Fecha inv\xE1lida: ${texto.slice(0, 40)}`);
+  if (/(Z|[+-]\d{2}:?\d{2})$/.test(texto)) return new Date(texto);
+  const comoUtc = /* @__PURE__ */ new Date(`${texto.length === 10 ? `${texto}T00:00:00` : texto}Z`);
+  if (Number.isNaN(comoUtc.getTime())) throw new RangeError(`Fecha inv\xE1lida: ${texto}`);
+  const pared = comoUtc.toISOString().slice(0, 19);
+  const candidatos = [-1, 1].map((d) => comoUtc.getTime() - piezas(new Date(comoUtc.getTime() + d * 864e5)).ms);
+  const t = candidatos.find((c) => {
+    const p = piezas(new Date(c));
+    return `${p.dia}T${p.hora}` === pared;
+  });
+  return new Date(t ?? candidatos[0]);
+}
+function normalizarFecha(texto) {
+  if (!texto) return null;
+  if (/^\d{4}/.test(texto) && Number(texto.slice(0, 4)) < 1990) return null;
+  return isoSantiago(desdeHoraSantiago(texto));
+}
+function ddmmaaaa(dia) {
+  const [a, m, d] = dia.split("-");
+  return `${d}${m}${a}`;
+}
+function sumarDias(dia, n) {
+  const d = /* @__PURE__ */ new Date(`${dia}T12:00:00Z`);
+  d.setUTCDate(d.getUTCDate() + n);
+  return d.toISOString().slice(0, 10);
+}
+function proximaMedianoche(ahora = /* @__PURE__ */ new Date()) {
+  return isoSantiago(desdeHoraSantiago(sumarDias(diaSantiago(ahora), 1)));
+}
+
+export {
+  __export,
+  isoSantiago,
+  diaSantiago,
+  desdeHoraSantiago,
+  normalizarFecha,
+  ddmmaaaa,
+  sumarDias,
+  proximaMedianoche
+};