@widergy/integration-docs

CLI para gestionar contratos OpenAPI de integración en los productos Widergy (Ruby y Node). Hace dos cosas:

1. import (one-time): genera un OpenAPI por integration desde la collection de Postman actual (nuestra doc), con un control (drift doc↔ejemplos reales + validación de ejemplos contra el schema). Se corre una vez por integration; después la collection vieja de Postman se descarta y la fuente de verdad pasa a ser el OpenAPI.
2. export (ongoing): genera la(s) collection(s) de Postman desde los OpenAPI, preservando todos los examples y las descripciones. La collection es un artefacto read-only gitignored — se trabaja sobre el OpenAPI, nunca sobre la collection.

Por qué un CLI de node (y no una rake)

Corre en cualquier producto sin importar su lenguaje (UGO/Customer-Hub en Ruby, Workspace-API en NestJS, productos node-puro). Los artefactos son JSON/YAML, nativos de JS.

Uso en un repo

1. npm i -D @widergy/integration-docs
2. Crear integration-docs.config.yml en la raíz (ver *.config.example.yml).
3. Comandos:

# IMPORT (one-time): crear el OpenAPI de una integration desde la collection vieja de Postman
npx integration-docs import account_data              # una
npx integration-docs import-all                       # todas las de importer.sources

# EXPORT (ongoing): generar la(s) collection(s) Postman desde los OpenAPI
npx integration-docs export                           # todas las collections del config
npx integration-docs export -c external               # una puntual

# REPORT: regenerar el backlog de reconciliación desde los OpenAPI (sin re-importar)
npx integration-docs report                           # todas las collections
npx integration-docs report -c external               # una puntual

Backlog de reconciliación (_reconciliation.md)

import-all deja siempre un _reconciliation.md en la raíz del specsDir (junto a _collection.md), trackeado en git. Es el worklist de contratos cuya doc no cierra con sus propios ejemplos. Se va achicando a medida que arreglás los YAML: corré report para regenerarlo (no necesita la collection vieja, lee los OpenAPI ya escritos). Buckets:

• 🔴 errores de schema (requerido faltante / type mismatch) — prioridad.
• 🟡 drift (keys en ejemplos no documentadas y viceversa).
• ⚪ sin schema (la doc no usa el formato de field-list parseable).
• ⚪ sin ejemplo de éxito para cruzar.

El field-list parser es plano: si la doc lista los campos de objetos anidados (items de un array, sub-objetos), los valida como top-level y los marca faltantes. Eso aparece como error de schema y es señal válida de reconciliación (el contrato debería modelar el anidamiento), pero no es lo mismo que un typo real (dirección vs direccion). Leé el detalle, no solo el número.

Estándar de carpetas

docs/integration/<collection>/<grupo1>/<grupoN>/<integration>.yml

Espeja la estructura de la collection de Postman. import escribe ahí (anidando por los grupos del path, sin el item hoja, con los prefijos de orden limpios: "g. Cuentas" → "Cuentas"). export camina ese árbol recursivo y reconstruye las carpetas en la collection.

Cómo sabe qué OpenAPIs usar

Cada collection del config declara su specsDir (raíz). El CLI solo camina ahí (recursivo). Para separar "estos sí / estos no" (contratos externos vs specs internos), cada grupo tiene su propio dir raíz y su collection. Podés tener N collections con distinto nombre, dir y salida.

Flujo end-to-end

[import, 1 vez]   collection Postman vieja ──import──▶ OpenAPI YAML (fuente, trackeado en git)
[de acá en más]   se edita el OpenAPI ──export──▶ collection Postman (gitignored)
                  el contract-test (en cada repo) valida ejemplos vs schema en CI

El control (al importar)

import compara el contrato contra los ejemplos reales de respuesta y reporta (no falla):

• drift: keys que están en los ejemplos pero no en la doc, y viceversa (cazó, p.ej., que la doc decía dirección y la realidad usa direccion).
• ejemplos que no cumplen el schema declarado.

Los ejemplos son respuestas reales documentadas, así que compararse contra ellos es el control de "la doc no está desactualizada". No depende del host ni de ningún archivo extra.

Qué NO se migra (importante)

El OpenAPI describe el contrato (qué expone el endpoint: request, response, examples, descripción). NO se lleva lo que es glue de runtime de Postman, porque OpenAPI no lo puede representar:

• Scripts (pre-request / post-response, p.ej. pm.collectionVariables.set, token-chaining, "Environment setup"): es JS imperativo, fuera del alcance de OpenAPI.
• Environments / credenciales: son secretos — no van a git ni al OpenAPI. Quedan en Postman / Postman Vault. La collection generada usa los placeholders {{baseUrl}}, {{apikey}}, etc., así que tus environments existentes siguen funcionando contra ella.
• Auth y variables a nivel collection: glue de testing, no contrato.

Si necesitás versionar una collection operativa con scripts/auth (las de testing por-utility), hacelo con su JSON nativo de Postman (p.ej. Postman Native Git), no con este tool: acá viven los contratos, no las collections operativas.