@openfactura/cli 0.0.0-stage → 0.2.0

package/dist/index.js

@@ -0,0 +1,2137 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { parseArgs } from "util";
+
+// package.json
+var package_default = {
+  name: "@openfactura/cli",
+  version: "0.2.0",
+  description: "Cliente de l\xEDnea de comandos y servidor MCP (stdio) de Open Factura: facturaci\xF3n electr\xF3nica de El Salvador (DTE).",
+  license: "MIT",
+  repository: {
+    type: "git",
+    url: "git+https://github.com/xaviigna/openfactura.git",
+    directory: "packages/cli"
+  },
+  homepage: "https://github.com/xaviigna/openfactura/tree/main/packages/cli#readme",
+  bugs: "https://github.com/xaviigna/openfactura/issues",
+  type: "module",
+  bin: {
+    openfactura: "dist/index.js"
+  },
+  files: [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  engines: {
+    node: ">=20"
+  },
+  publishConfig: {
+    access: "public"
+  },
+  keywords: [
+    "dte",
+    "el-salvador",
+    "factura-electronica",
+    "hacienda",
+    "mcp",
+    "cli"
+  ],
+  scripts: {
+    build: "tsup",
+    dev: "tsx src/index.ts",
+    test: "vitest run",
+    "type-check": "tsc --noEmit"
+  },
+  dependencies: {
+    "@modelcontextprotocol/server": "^2.4.0",
+    zod: "^4.0.0"
+  },
+  devDependencies: {
+    "@types/node": "^22.0.0",
+    tsup: "^8.5.0",
+    tsx: "^4.20.0",
+    typescript: "^5.9.0",
+    vitest: "^4.1.0"
+  }
+};
+
+// src/comandos.ts
+import { randomUUID } from "crypto";
+import { readFile, writeFile } from "fs/promises";
+import { basename, resolve } from "path";
+
+// src/config.ts
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, isAbsolute, join } from "path";
+
+// src/errores.ts
+var SALIDA = { ok: 0, error: 1, uso: 2, noAutenticado: 3, limite: 4 };
+var ErrorUso = class extends Error {
+};
+var ErrorCli = class extends Error {
+  constructor(message, code = "error", salida = SALIDA.error) {
+    super(message);
+    this.code = code;
+    this.salida = salida;
+  }
+  code;
+  salida;
+  get cuerpo() {
+    return { error: { code: this.code, message: this.message } };
+  }
+};
+var ErrorApi = class extends Error {
+  constructor(status, cuerpo, retryAfter = null) {
+    super(cuerpo.error.message);
+    this.status = status;
+    this.cuerpo = cuerpo;
+    this.retryAfter = retryAfter;
+  }
+  status;
+  cuerpo;
+  retryAfter;
+  get code() {
+    return this.cuerpo.error.code;
+  }
+  get details() {
+    return this.cuerpo.error.details;
+  }
+  get salida() {
+    if (this.status === 401) return SALIDA.noAutenticado;
+    if (this.status === 429) return SALIDA.limite;
+    return SALIDA.error;
+  }
+};
+
+// src/config.ts
+var URL_POR_DEFECTO = "http://localhost:8788";
+function rutaConfig(env) {
+  const xdg = env.XDG_CONFIG_HOME;
+  const base = xdg && isAbsolute(xdg) ? xdg : join(env.HOME || homedir(), ".config");
+  return join(base, "openfactura", "config.json");
+}
+function leerConfig(env) {
+  const ruta2 = rutaConfig(env);
+  let texto2;
+  try {
+    texto2 = readFileSync(ruta2, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") return { perfiles: {} };
+    throw new ErrorCli(`No se pudo leer ${ruta2}: ${error.message}`, "config_ilegible");
+  }
+  try {
+    const datos = JSON.parse(texto2);
+    const perfiles = datos && typeof datos.perfiles === "object" && datos.perfiles ? datos.perfiles : {};
+    return { perfiles: { ...perfiles } };
+  } catch {
+    throw new ErrorCli(`${ruta2} no es un JSON v\xE1lido. Corr\xEDjalo o b\xF3rrelo.`, "config_ilegible");
+  }
+}
+function guardarConfig(env, config) {
+  const ruta2 = rutaConfig(env);
+  const carpeta = dirname(ruta2);
+  mkdirSync(carpeta, { recursive: true, mode: 448 });
+  chmodSync(carpeta, 448);
+  const temporal = `${ruta2}.${process.pid}.tmp`;
+  rmSync(temporal, { force: true });
+  writeFileSync(temporal, `${JSON.stringify(config, null, 2)}
+`, { mode: 384, flag: "wx" });
+  chmodSync(temporal, 384);
+  renameSync(temporal, ruta2);
+  return ruta2;
+}
+function normalizarUrl(valor) {
+  let url;
+  try {
+    url = new URL(valor.trim());
+  } catch {
+    throw new ErrorUso(`URL del servidor inv\xE1lida: ${valor}`);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new ErrorUso(`La URL del servidor debe empezar con http:// o https://: ${valor}`);
+  }
+  if (url.username || url.password) {
+    throw new ErrorUso("La URL del servidor no debe llevar usuario ni contrase\xF1a");
+  }
+  const ruta2 = url.pathname.replace(/\/+$/, "").replace(/\/api\/v1$/, "");
+  return `${url.origin}${ruta2}`;
+}
+function nombrePerfil(env, opcion) {
+  const nombre = opcion || env.OPENFACTURA_PROFILE || "default";
+  if (!/^[\w.-]{1,64}$/.test(nombre) || nombre === "__proto__") {
+    throw new ErrorUso(`Nombre de perfil inv\xE1lido: ${nombre}`);
+  }
+  return nombre;
+}
+function resolver(env, opciones = {}) {
+  const perfil = nombrePerfil(env, opciones.perfil);
+  const guardado = leerConfig(env).perfiles[perfil] ?? {};
+  let url = URL_POR_DEFECTO;
+  let origenUrl = "defecto";
+  if (opciones.url) {
+    url = opciones.url;
+    origenUrl = "opci\xF3n";
+  } else if (env.OPENFACTURA_URL) {
+    url = env.OPENFACTURA_URL;
+    origenUrl = "entorno";
+  } else if (guardado.url) {
+    url = guardado.url;
+    origenUrl = "config";
+  }
+  const deEntorno = env.OPENFACTURA_API_KEY?.trim();
+  const apiKey = deEntorno || guardado.apiKey || null;
+  return {
+    perfil,
+    url: normalizarUrl(url),
+    origenUrl,
+    apiKey,
+    origenClave: deEntorno ? "entorno" : apiKey ? "config" : null
+  };
+}
+function enmascarar(clave) {
+  return `${clave.slice(0, 14)}\u2026`;
+}
+var esClaveValida = (clave) => /^of_(test|live)_\S+$/.test(clave);
+var esClaveDeProduccion = (clave) => clave.startsWith("of_live_");
+
+// src/esquemas.ts
+import { z } from "zod";
+var TIPOS_DTE = {
+  "01": "Factura",
+  "03": "Comprobante de Cr\xE9dito Fiscal",
+  "04": "Nota de Remisi\xF3n",
+  "05": "Nota de Cr\xE9dito",
+  "06": "Nota de D\xE9bito",
+  "07": "Comprobante de Retenci\xF3n",
+  "11": "Factura de Exportaci\xF3n",
+  "14": "Factura de Sujeto Excluido"
+};
+var ESTADOS_DTE = [
+  "pendiente",
+  "procesado",
+  "rechazado",
+  "contingencia",
+  "invalidado"
+];
+var NOMBRE_AMBIENTE = { "00": "Pruebas", "01": "Producci\xF3n" };
+var codigosTipo = Object.keys(TIPOS_DTE);
+var texto = (max = 250) => z.string().trim().min(1).max(max);
+var opcional = (max = 250) => z.string().trim().max(max).nullish().transform((v) => v || null);
+var tipoDte = z.enum(codigosTipo);
+var cliente = z.object({
+  tipoDocumento: z.enum(["36", "13", "03", "02", "37"]),
+  numDocumento: texto(20),
+  nrc: opcional(8),
+  nombre: texto(),
+  nombreComercial: opcional(150),
+  codActividad: opcional(6),
+  descActividad: opcional(150),
+  departamento: opcional(2),
+  municipio: opcional(2),
+  distrito: opcional(2),
+  complemento: opcional(200),
+  telefono: opcional(30),
+  correo: z.union([z.email().max(100), z.literal("")]).nullish().transform((v) => v || null)
+});
+var producto = z.object({
+  codigo: texto(25),
+  descripcion: texto(1e3),
+  precioUnitario: z.number().nonnegative().max(99999999999),
+  tipoItem: z.union([z.literal(1), z.literal(2), z.literal(3), z.literal(4)]).default(1),
+  uniMedida: z.number().int().min(1).max(99).default(59),
+  tipoVenta: z.enum(["gravada", "exenta", "noSujeta"]).default("gravada")
+});
+var persona = z.object({
+  nombre: texto(100),
+  tipoDocumento: z.string().min(2).max(2),
+  numDocumento: texto(20)
+});
+var invalidacion = z.object({
+  tipoAnulacion: z.union([z.literal(1), z.literal(2), z.literal(3)]),
+  motivoAnulacion: opcional(250),
+  codigoGeneracionReemplazo: opcional(36),
+  solicitante: persona.optional(),
+  responsable: persona.optional()
+});
+var fecha = z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Use el formato AAAA-MM-DD");
+var retorno = z.object({
+  items: z.array(
+    z.object({
+      descripcion: texto(1e3),
+      cantidad: z.number().positive(),
+      precioUni: z.number().nonnegative(),
+      tipoItem: z.union([z.literal(1), z.literal(2), z.literal(3), z.literal(4)]).optional(),
+      codigo: opcional(25),
+      uniMedida: z.number().int().min(1).max(99).optional(),
+      descuento: z.number().nonnegative().optional(),
+      tipoVenta: z.enum(["gravada", "exenta", "noSujeta"]).optional(),
+      seguro: z.number().nonnegative().optional(),
+      flete: z.number().nonnegative().optional()
+    })
+  ).min(1).max(2e3).describe(
+    "Bienes que se retornan. precioUni: en Factura (01) CON IVA, como en la factura; en Exportaci\xF3n (11) y Sujeto Excluido (14) SIN IVA."
+  )
+});
+var operacionesEspeciales = z.object({
+  tipoDocumento: z.enum(["02", "97"]).describe("02 factura de venta simplificada (por rangos), 97 comprobante de control interno"),
+  fecha: fecha.optional().describe("Fecha del evento; define el periodo informado"),
+  items: z.array(
+    z.object({
+      descripcion: texto(1500),
+      precioUni: z.number().nonnegative().describe("SIN IVA"),
+      cantidad: z.number().int().positive().optional(),
+      numDocumento: opcional(36),
+      docDel: z.string().trim().min(1).max(36).optional(),
+      docAl: z.string().trim().min(1).max(36).optional(),
+      fechaEmision: fecha.optional(),
+      tipoVenta: z.enum(["gravada", "exenta", "noSujeta"]).optional(),
+      codigoGeneracionRef: z.string().length(36).optional()
+    })
+  ).min(1).max(2e3)
+});
+var EVENTOS_WEBHOOK = [
+  "dte.procesado",
+  "dte.rechazado",
+  "dte.contingencia",
+  "dte.invalidado",
+  "retorno.procesado",
+  "operaciones_especiales.procesado"
+];
+var webhook = z.object({
+  url: z.string().max(2e3).describe("URL https:// p\xFAblica que recibir\xE1 los POST firmados"),
+  descripcion: opcional(200),
+  eventos: z.array(z.enum(EVENTOS_WEBHOOK)).min(1).describe("Eventos a los que se suscribe"),
+  activo: z.boolean().optional()
+});
+
+// src/http.ts
+var TIEMPO_LIMITE_MS = 6e4;
+var ClienteApi = class {
+  url;
+  opciones;
+  constructor(opciones) {
+    this.opciones = opciones;
+    this.url = opciones.url;
+  }
+  async pedir(metodo, ruta2, peticion = {}) {
+    const respuesta = await this.enviar(metodo, ruta2, peticion);
+    const texto2 = await respuesta.text();
+    let datos = null;
+    if (texto2) {
+      try {
+        datos = JSON.parse(texto2);
+      } catch {
+        throw new ErrorCli(
+          `El servidor respondi\xF3 algo que no es JSON (HTTP ${respuesta.status}). Revise la URL: ${this.url}`,
+          "respuesta_invalida"
+        );
+      }
+    }
+    return { status: respuesta.status, headers: respuesta.headers, datos };
+  }
+  /** Descarga binaria (PDF). */
+  async descargar(ruta2) {
+    const respuesta = await this.enviar("GET", ruta2, {});
+    return new Uint8Array(await respuesta.arrayBuffer());
+  }
+  async enviar(metodo, ruta2, { query, cuerpo, headers }) {
+    const destino = new URL(`${this.url}/api/v1${ruta2}`);
+    for (const [clave, valor] of Object.entries(query ?? {})) {
+      if (valor !== void 0 && valor !== null && valor !== "")
+        destino.searchParams.set(clave, String(valor));
+    }
+    const { apiKey, version, timeoutMs = TIEMPO_LIMITE_MS } = this.opciones;
+    const hacerFetch = this.opciones.fetch ?? fetch;
+    let respuesta;
+    try {
+      respuesta = await hacerFetch(destino, {
+        method: metodo,
+        headers: {
+          Authorization: `Bearer ${apiKey}`,
+          "User-Agent": `openfactura-cli/${version}`,
+          Accept: "application/json",
+          ...cuerpo === void 0 ? {} : { "Content-Type": "application/json" },
+          ...headers
+        },
+        body: cuerpo === void 0 ? void 0 : JSON.stringify(cuerpo),
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+    } catch (error) {
+      const nombre = error?.name;
+      if (nombre === "TimeoutError" || nombre === "AbortError") {
+        throw new ErrorCli(
+          `El servidor no respondi\xF3 en ${Math.round(timeoutMs / 1e3)} s (${this.url})`,
+          "tiempo_agotado"
+        );
+      }
+      const causa = error?.cause;
+      const detalle = causa?.code || causa?.message || error?.message || "error de red";
+      throw new ErrorCli(`No se pudo conectar con ${this.url} (${detalle})`, "sin_conexion");
+    }
+    if (!respuesta.ok) throw await leerError(respuesta);
+    return respuesta;
+  }
+};
+async function leerError(respuesta) {
+  const texto2 = await respuesta.text().catch(() => "");
+  let cuerpo = null;
+  try {
+    const json = JSON.parse(texto2);
+    const e = json?.error;
+    if (e && typeof e.code === "string" && typeof e.message === "string") {
+      cuerpo = {
+        error: {
+          code: e.code,
+          message: e.message,
+          ...e.details === void 0 ? {} : { details: e.details }
+        }
+      };
+    }
+  } catch {
+  }
+  cuerpo ??= {
+    error: {
+      code: `http_${respuesta.status}`,
+      message: `El servidor respondi\xF3 HTTP ${respuesta.status}${respuesta.statusText ? ` ${respuesta.statusText}` : ""}`
+    }
+  };
+  const espera = Number.parseInt(respuesta.headers.get("Retry-After") ?? "", 10);
+  return new ErrorApi(respuesta.status, cuerpo, Number.isFinite(espera) ? espera : null);
+}
+
+// src/mcp.ts
+import { McpServer } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { z as z2 } from "zod";
+var listaTipos = Object.entries(TIPOS_DTE).map(([codigo, nombre]) => `${codigo} ${nombre}`).join(", ");
+var DATOS_DTE = `Datos del documento. Campos habituales:
+- items: [{ descripcion, cantidad, precioUni, tipoItem?: 1 bien | 2 servicio, codigo?, uniMedida?: 59 unidad, descuento?, tipoVenta?: 'gravada'|'exenta'|'noSujeta' }]. En Factura (01) precioUni INCLUYE IVA; en CCF (03), notas y remisi\xF3n va SIN IVA.
+- receptor: { nit o tipoDocumento+numDocumento, nrc, nombre, codActividad, descActividad, direccion: { departamento, municipio, distrito, complemento }, telefono, correo }. En Factura es opcional bajo USD 25,000. Puede omitirse si env\xEDa clienteId.
+- condicionOperacion?: 1 contado | 2 cr\xE9dito | 3 otro; pagos?; credito?: { plazo, periodo }.
+- documentosRelacionados (notas de cr\xE9dito/d\xE9bito): [{ tipoDocumento, tipoGeneracion: 2, numeroDocumento: <c\xF3digo de generaci\xF3n>, fechaEmision }].
+Los c\xF3digos de cat\xE1logo se consultan con catalogo_buscar.`;
+var entradaEmision = {
+  tipoDte: tipoDte.describe(`Tipo de documento: ${listaTipos}`),
+  datos: z2.record(z2.string(), z2.unknown()).describe(DATOS_DTE),
+  clienteId: z2.string().optional().describe("Id de un cliente guardado para usarlo como receptor"),
+  puntoVentaId: z2.string().optional().describe("Punto de venta emisor; por defecto el primero")
+};
+async function responder(accion) {
+  try {
+    const { datos } = await accion();
+    return {
+      content: [{ type: "text", text: JSON.stringify(datos, null, 2) }],
+      structuredContent: { resultado: datos }
+    };
+  } catch (error) {
+    const cuerpo = error instanceof ErrorApi || error instanceof ErrorCli ? error.cuerpo : { error: { code: "error_interno", message: "Ocurri\xF3 un error inesperado" } };
+    return { content: [{ type: "text", text: JSON.stringify(cuerpo, null, 2) }], isError: true };
+  }
+}
+var lectura = { readOnlyHint: true, openWorldHint: false };
+var ruta = (segmento2) => encodeURIComponent(segmento2);
+function crearServidorMcp(api, version) {
+  const servidor = new McpServer({ name: "openfactura", version });
+  servidor.registerTool(
+    "emisor_obtener",
+    {
+      title: "Ver emisor",
+      description: "Datos fiscales del emisor, sus establecimientos y puntos de venta, el ambiente activo (00 pruebas, 01 producci\xF3n) y si las credenciales del MH est\xE1n cargadas.",
+      inputSchema: z2.object({}),
+      annotations: lectura
+    },
+    () => responder(() => api.pedir("GET", "/emisor"))
+  );
+  servidor.registerTool(
+    "catalogo_buscar",
+    {
+      title: "Buscar en cat\xE1logos del MH",
+      description: "Consulta un cat\xE1logo oficial (CAT-001 \u2026 CAT-033): CAT-012 departamentos, CAT-013 municipios, CAT-008 distritos, CAT-019 actividades econ\xF3micas, CAT-014 unidades de medida, CAT-017 formas de pago, CAT-022 tipos de documento. Sin `id` devuelve la lista de cat\xE1logos.",
+      inputSchema: z2.object({
+        id: z2.string().optional().describe("Por ejemplo CAT-019"),
+        q: z2.string().optional().describe("Texto a buscar en el c\xF3digo o la descripci\xF3n"),
+        departamento: z2.string().optional().describe("Filtra municipios o distritos por departamento")
+      }),
+      annotations: lectura
+    },
+    ({ id, q, departamento }) => responder(
+      () => id ? api.pedir("GET", `/catalogos/${ruta(id.toUpperCase())}`, {
+        query: { q, departamento, limite: 50 }
+      }) : api.pedir("GET", "/catalogos")
+    )
+  );
+  servidor.registerTool(
+    "clientes_buscar",
+    {
+      title: "Buscar clientes",
+      description: "Busca clientes guardados por nombre o n\xFAmero de documento.",
+      inputSchema: z2.object({ q: z2.string().optional() }),
+      annotations: lectura
+    },
+    ({ q }) => responder(() => api.pedir("GET", "/clientes", { query: { q, limite: 25 } }))
+  );
+  servidor.registerTool(
+    "cliente_crear",
+    {
+      title: "Crear cliente",
+      description: "Guarda un cliente para reutilizarlo como receptor. tipoDocumento: 36 NIT, 13 DUI, 03 pasaporte, 02 carn\xE9 de residente, 37 otro.",
+      inputSchema: cliente,
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
+    },
+    (datos) => responder(() => api.pedir("POST", "/clientes", { cuerpo: datos }))
+  );
+  servidor.registerTool(
+    "productos_buscar",
+    {
+      title: "Buscar productos",
+      description: "Busca productos y servicios guardados por c\xF3digo o descripci\xF3n. El precio guardado es SIN IVA.",
+      inputSchema: z2.object({ q: z2.string().optional() }),
+      annotations: lectura
+    },
+    ({ q }) => responder(() => api.pedir("GET", "/productos", { query: { q, limite: 25 } }))
+  );
+  servidor.registerTool(
+    "producto_crear",
+    {
+      title: "Crear producto",
+      description: "Guarda un producto o servicio. precioUnitario va SIN IVA.",
+      inputSchema: producto,
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
+    },
+    (datos) => responder(() => api.pedir("POST", "/productos", { cuerpo: datos }))
+  );
+  servidor.registerTool(
+    "dte_validar",
+    {
+      title: "Validar un DTE sin emitirlo",
+      description: "Construye el documento y lo valida contra el esquema oficial del MH. No consume n\xFAmero de control, no firma y no transmite. \xDAselo antes de dte_emitir.",
+      inputSchema: z2.object(entradaEmision),
+      annotations: lectura
+    },
+    (entrada) => responder(() => api.pedir("POST", "/dte/validar", { cuerpo: entrada }))
+  );
+  servidor.registerTool(
+    "dte_emitir",
+    {
+      title: "Emitir un DTE",
+      description: 'Emite un documento tributario electr\xF3nico: lo firma y lo transmite al Ministerio de Hacienda. Tiene efecto fiscal y consume un n\xFAmero de control. Confirme los datos con el usuario antes de llamar. Devuelve estado "procesado" con sello, o "contingencia" si el MH no respondi\xF3.',
+      inputSchema: z2.object({
+        ...entradaEmision,
+        idempotencyKey: z2.string().min(8).max(200).describe(
+          "Identificador \xFAnico de este intento. Repetirlo devuelve el mismo resultado sin emitir dos veces."
+        )
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    ({ idempotencyKey, ...entrada }) => responder(
+      () => api.pedir("POST", "/dte", {
+        cuerpo: entrada,
+        headers: { "Idempotency-Key": idempotencyKey }
+      })
+    )
+  );
+  servidor.registerTool(
+    "dte_listar",
+    {
+      title: "Listar documentos",
+      description: "Lista los DTE del ambiente activo, del m\xE1s reciente al m\xE1s antiguo.",
+      inputSchema: z2.object({
+        tipo: tipoDte.optional(),
+        estado: z2.enum(ESTADOS_DTE).optional(),
+        q: z2.string().optional().describe("Receptor, n\xFAmero de control o c\xF3digo de generaci\xF3n"),
+        desde: z2.string().optional().describe("AAAA-MM-DD"),
+        hasta: z2.string().optional().describe("AAAA-MM-DD"),
+        pagina: z2.number().int().min(1).optional()
+      }),
+      annotations: lectura
+    },
+    (filtros) => responder(
+      () => api.pedir("GET", "/dte", { query: { pagina: 1, porPagina: 25, ...filtros } })
+    )
+  );
+  servidor.registerTool(
+    "dte_obtener",
+    {
+      title: "Ver un documento",
+      description: "Detalle de un DTE por c\xF3digo de generaci\xF3n: estado, sello, JSON oficial, respuesta del MH, eventos y enlace de consulta p\xFAblica.",
+      inputSchema: z2.object({ codigoGeneracion: z2.string() }),
+      annotations: lectura
+    },
+    ({ codigoGeneracion }) => responder(() => api.pedir("GET", `/dte/${ruta(codigoGeneracion)}`))
+  );
+  servidor.registerTool(
+    "dte_invalidar",
+    {
+      title: "Invalidar un DTE",
+      description: "Transmite el evento de invalidaci\xF3n de un DTE procesado, o de un evento de retorno u operaciones especiales (use su c\xF3digo de generaci\xF3n). Un DTE con retorno vigente exige invalidar antes el retorno. Es irreversible y tiene efecto fiscal: confirme con el usuario. tipoAnulacion: 1 error en la informaci\xF3n (requiere codigoGeneracionReemplazo), 2 rescindir la operaci\xF3n, 3 otro (requiere motivo y reemplazo).",
+      inputSchema: z2.object({ codigoGeneracion: z2.string(), ...invalidacion.shape }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: true
+      }
+    },
+    ({ codigoGeneracion, ...entrada }) => responder(
+      () => api.pedir("POST", `/dte/${ruta(codigoGeneracion)}/invalidar`, { cuerpo: entrada })
+    )
+  );
+  servidor.registerTool(
+    "dte_retorno",
+    {
+      title: "Registrar un retorno (evento 18)",
+      description: "Transmite un Evento de Retorno sobre una Factura (01), Factura de Exportaci\xF3n (11) o Sujeto Excluido (14) procesados: devoluci\xF3n de bienes, reembolso o envases, sin invalidar el documento. Plazo: 3 meses desde la fecha del DTE. La suma de retornos no puede superar el DTE. Tiene efecto fiscal: confirme con el usuario. Para un Cr\xE9dito Fiscal use una Nota de Cr\xE9dito (05).",
+      inputSchema: z2.object({
+        codigoGeneracion: z2.string().describe("C\xF3digo de generaci\xF3n del DTE original"),
+        ...retorno.shape,
+        idempotencyKey: z2.string().min(8).max(200).describe(
+          "Identificador \xFAnico de este intento. Repetirlo devuelve el mismo resultado sin transmitir dos veces."
+        )
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    ({ codigoGeneracion, idempotencyKey, ...entrada }) => responder(
+      () => api.pedir("POST", `/dte/${ruta(codigoGeneracion)}/retorno`, {
+        cuerpo: entrada,
+        headers: { "Idempotency-Key": idempotencyKey }
+      })
+    )
+  );
+  servidor.registerTool(
+    "operaciones_especiales_informar",
+    {
+      title: "Informar operaciones especiales (evento 17)",
+      description: "Transmite un Evento de Operaciones Especiales: informa al MH las facturas simplificadas (02, siempre por rangos docDel\u2013docAl) o los comprobantes de control interno (97, uno a uno con numDocumento o por rangos, sin mezclar) de un periodo. precioUni SIN IVA. Los documentos anulados van en un evento aparte con codigoGeneracionRef. Tiene efecto fiscal: confirme con el usuario.",
+      inputSchema: z2.object({
+        ...operacionesEspeciales.shape,
+        idempotencyKey: z2.string().min(8).max(200).describe(
+          "Identificador \xFAnico de este intento. Repetirlo devuelve el mismo resultado sin transmitir dos veces."
+        )
+      }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    },
+    ({ idempotencyKey, ...entrada }) => responder(
+      () => api.pedir("POST", "/eventos/operaciones-especiales", {
+        cuerpo: entrada,
+        headers: { "Idempotency-Key": idempotencyKey }
+      })
+    )
+  );
+  servidor.registerTool(
+    "eventos_listar",
+    {
+      title: "Listar eventos",
+      description: "Eventos de retorno y de operaciones especiales del ambiente activo (los 50 m\xE1s recientes).",
+      inputSchema: z2.object({ tipo: z2.enum(["retorno", "operaciones_especiales"]).optional() }),
+      annotations: lectura
+    },
+    ({ tipo }) => responder(() => api.pedir("GET", "/eventos", { query: { tipo } }))
+  );
+  servidor.registerTool(
+    "evento_obtener",
+    {
+      title: "Ver un evento",
+      description: "Detalle de un evento por c\xF3digo de generaci\xF3n: estado, sello, JSON oficial y respuesta del MH.",
+      inputSchema: z2.object({ codigoGeneracion: z2.string() }),
+      annotations: lectura
+    },
+    ({ codigoGeneracion }) => responder(() => api.pedir("GET", `/eventos/${ruta(codigoGeneracion)}`))
+  );
+  servidor.registerTool(
+    "webhooks_listar",
+    {
+      title: "Listar webhooks",
+      description: "Webhooks de la organizaci\xF3n: URL, eventos suscritos y si est\xE1n activos. Nunca devuelve el secreto de firma.",
+      inputSchema: z2.object({}),
+      annotations: lectura
+    },
+    () => responder(() => api.pedir("GET", "/webhooks"))
+  );
+  servidor.registerTool(
+    "webhook_crear",
+    {
+      title: "Crear webhook",
+      description: `Registra una URL https:// que recibir\xE1 un POST firmado cuando cambie el estado de un documento. Eventos: ${EVENTOS_WEBHOOK.join(", ")}. Devuelve el secreto de firma (whsec_\u2026) UNA sola vez: entr\xE9gueselo al usuario para que verifique la firma OpenFactura-Signature.`,
+      inputSchema: webhook,
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false }
+    },
+    (datos) => responder(() => api.pedir("POST", "/webhooks", { cuerpo: datos }))
+  );
+  servidor.registerTool(
+    "webhook_eliminar",
+    {
+      title: "Eliminar webhook",
+      description: "Elimina un webhook y su historial de entregas. Deja de recibir notificaciones de inmediato. Confirme con el usuario.",
+      inputSchema: z2.object({ id: z2.string() }),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      }
+    },
+    ({ id }) => responder(() => api.pedir("DELETE", `/webhooks/${ruta(id)}`))
+  );
+  servidor.registerTool(
+    "webhook_probar",
+    {
+      title: "Probar webhook",
+      description: "Env\xEDa ya un evento webhook.prueba firmado a la URL del webhook y devuelve si respondi\xF3 2xx, su estado HTTP o el error.",
+      inputSchema: z2.object({ id: z2.string() }),
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true }
+    },
+    ({ id }) => responder(() => api.pedir("POST", `/webhooks/${ruta(id)}/probar`))
+  );
+  return servidor;
+}
+function servirMcp(api, version) {
+  return new Promise((resolve2) => {
+    const conexion = serveStdio(() => crearServidorMcp(api, version), {
+      onerror: (error) => process.stderr.write(`openfactura mcp: ${error.message}
+`)
+    });
+    const cerrar = () => void conexion.close().finally(resolve2);
+    process.stdin.once("end", cerrar);
+    process.stdin.once("close", cerrar);
+  });
+}
+
+// src/salida.ts
+var ANCHO_MAXIMO = 44;
+var celda = (valor) => {
+  if (valor === null || valor === void 0 || valor === "") return "\u2014";
+  const texto2 = String(valor).replace(/\s+/g, " ");
+  return texto2.length > ANCHO_MAXIMO ? `${texto2.slice(0, ANCHO_MAXIMO - 1)}\u2026` : texto2;
+};
+function tabla(encabezados, filas, derecha = []) {
+  const celdas = filas.map((fila) => fila.map(celda));
+  const anchos = encabezados.map(
+    (titulo, i) => Math.max(titulo.length, ...celdas.map((fila) => fila[i]?.length ?? 0))
+  );
+  const linea = (fila) => fila.map(
+    (texto2, i) => derecha.includes(i) ? texto2.padStart(anchos[i] ?? 0) : texto2.padEnd(anchos[i] ?? 0)
+  ).join("  ").trimEnd();
+  return [linea(encabezados.map((t) => t.toUpperCase())), ...celdas.map(linea)].join("\n");
+}
+function fichas(pares) {
+  const visibles = pares.filter(
+    ([, valor]) => valor !== null && valor !== void 0 && valor !== ""
+  );
+  const ancho = Math.max(0, ...visibles.map(([clave]) => clave.length));
+  return visibles.map(([clave, valor]) => `${`${clave}:`.padEnd(ancho + 2)}${String(valor)}`).join("\n");
+}
+var dinero = (valor) => typeof valor === "number" ? `$${valor.toFixed(2)}` : "\u2014";
+var siNo = (valor) => valor ? "s\xED" : "no";
+
+// src/comandos.ts
+var nombreTipo = (codigo) => `${codigo} ${TIPOS_DTE[String(codigo)] ?? ""}`.trim();
+var nombreAmbiente = (codigo) => `${codigo} ${NOMBRE_AMBIENTE[String(codigo)] ?? ""}`.trim();
+var fecha2 = (ms) => typeof ms === "number" ? new Date(ms).toISOString().replace("T", " ").slice(0, 19) : ms;
+var segmento = (texto2) => encodeURIComponent(texto2);
+function mostrar(ctx, datos, legible) {
+  ctx.ent.stdout(ctx.json ? JSON.stringify(datos, null, 2) : legible());
+}
+async function leerJson(ctx, origen) {
+  let texto2;
+  if (origen === "-") {
+    texto2 = await ctx.ent.leerEntrada();
+  } else {
+    try {
+      texto2 = await readFile(resolve(ctx.ent.cwd, origen), "utf8");
+    } catch (error) {
+      throw new ErrorUso(`No se pudo leer ${origen}: ${error.message}`);
+    }
+  }
+  try {
+    return JSON.parse(texto2);
+  } catch (error) {
+    throw new ErrorUso(
+      `${origen === "-" ? "La entrada est\xE1ndar" : origen} no es un JSON v\xE1lido: ${error.message}`
+    );
+  }
+}
+async function leerEmision(ctx, origen) {
+  const cuerpo = await leerJson(ctx, origen);
+  const valido = cuerpo && typeof cuerpo === "object" && !Array.isArray(cuerpo) && "tipoDte" in cuerpo && "datos" in cuerpo;
+  if (!valido) {
+    throw new ErrorUso(
+      'El archivo debe ser un objeto { "tipoDte": "01", "datos": { \u2026 }, "clienteId"?, "puntoVentaId"? }'
+    );
+  }
+  return cuerpo;
+}
+async function confirmar(ctx, accion, entradaOcupada = false) {
+  if (ctx.si || !ctx.cfg.apiKey || !esClaveDeProduccion(ctx.cfg.apiKey)) return;
+  if (!ctx.ent.esTTY || entradaOcupada) {
+    throw new ErrorUso(
+      `Va a ${accion} en PRODUCCI\xD3N y no hay una terminal para confirmar: agregue --yes.`
+    );
+  }
+  const respuesta = await ctx.ent.preguntar(
+    `Va a ${accion} en PRODUCCI\xD3N (clave of_live_). \xBFContinuar? [s/N] `
+  );
+  if (!/^(s|si|sí|y|yes)$/i.test(respuesta.trim()))
+    throw new ErrorCli("Operaci\xF3n cancelada.", "cancelado");
+}
+function entero(ctx, opcion, minimo = 1) {
+  const texto2 = ctx.op(opcion);
+  if (texto2 === void 0) return void 0;
+  const numero = Number(texto2);
+  if (!Number.isInteger(numero) || numero < minimo)
+    throw new ErrorUso(`--${opcion} debe ser un n\xFAmero entero (recibido: ${texto2})`);
+  return numero;
+}
+function fichaDocumento(doc) {
+  return fichas([
+    ["Estado", doc.estado],
+    ["Tipo", nombreTipo(doc.tipoDte)],
+    ["N\xFAmero de control", doc.numeroControl],
+    ["C\xF3digo de generaci\xF3n", doc.codigoGeneracion],
+    ["Ambiente", nombreAmbiente(doc.ambiente)],
+    ["Emisi\xF3n", `${doc.fechaEmision ?? ""} ${doc.horaEmision ?? ""}`.trim()],
+    ["Receptor", [doc.receptorNombre, doc.receptorDocumento].filter(Boolean).join(" \xB7 ")],
+    ["Total", dinero(doc.total)],
+    ["Sello recibido", doc.selloRecibido],
+    ["Origen", doc.origen],
+    ["Error", doc.error],
+    ["Consulta p\xFAblica", doc.urlConsulta]
+  ]);
+}
+async function cuerpoDeAlta(ctx, campos, numericos = []) {
+  const dados = Object.keys(campos).filter((opcion) => ctx.op(opcion) !== void 0);
+  const archivo = ctx.op("file");
+  if (archivo !== void 0) {
+    if (dados.length) throw new ErrorUso("Use --file o las opciones sueltas, no ambas.");
+    return leerJson(ctx, archivo);
+  }
+  if (!dados.length) {
+    throw new ErrorUso(
+      `Indique --file <archivo.json> o los datos con opciones: ${Object.keys(campos).map((o) => `--${o}`).join(", ")}`
+    );
+  }
+  const cuerpo = {};
+  for (const opcion of dados) {
+    const texto2 = ctx.op(opcion);
+    const campo = campos[opcion];
+    if (numericos.includes(opcion)) {
+      const numero = Number(texto2);
+      if (texto2.trim() === "" || !Number.isFinite(numero))
+        throw new ErrorUso(`--${opcion} debe ser un n\xFAmero (recibido: ${texto2})`);
+      cuerpo[campo] = numero;
+    } else {
+      cuerpo[campo] = texto2;
+    }
+  }
+  return cuerpo;
+}
+var CAMPOS_CLIENTE = {
+  "tipo-documento": "tipoDocumento",
+  "num-documento": "numDocumento",
+  nrc: "nrc",
+  nombre: "nombre",
+  "nombre-comercial": "nombreComercial",
+  "cod-actividad": "codActividad",
+  "desc-actividad": "descActividad",
+  departamento: "departamento",
+  municipio: "municipio",
+  distrito: "distrito",
+  complemento: "complemento",
+  telefono: "telefono",
+  correo: "correo"
+};
+var CAMPOS_PRODUCTO = {
+  codigo: "codigo",
+  descripcion: "descripcion",
+  precio: "precioUnitario",
+  "tipo-item": "tipoItem",
+  "uni-medida": "uniMedida",
+  "tipo-venta": "tipoVenta"
+};
+async function login(ctx) {
+  let clave = ctx.op("key");
+  if (clave === void 0) {
+    clave = ctx.ent.esTTY ? await ctx.ent.preguntar("Clave de API (of_test_\u2026 u of_live_\u2026): ", true) : (await ctx.ent.leerEntrada()).split("\n")[0];
+  }
+  clave = (clave ?? "").trim();
+  if (!esClaveValida(clave))
+    throw new ErrorUso("La clave de API debe empezar con of_test_ o of_live_.");
+  const api = new ClienteApi({
+    url: ctx.cfg.url,
+    apiKey: clave,
+    version: ctx.version,
+    fetch: ctx.ent.fetch
+  });
+  const { datos } = await api.pedir("GET", "/yo");
+  const config = leerConfig(ctx.ent.env);
+  config.perfiles[ctx.cfg.perfil] = { url: ctx.cfg.url, apiKey: clave };
+  const ruta2 = guardarConfig(ctx.ent.env, config);
+  mostrar(
+    ctx,
+    datos,
+    () => [
+      `Sesi\xF3n iniciada en ${ctx.cfg.url}`,
+      fichas([
+        ["Clave", enmascarar(clave)],
+        ["Ambiente", nombreAmbiente(datos.ambiente)],
+        ["Perfil", ctx.cfg.perfil],
+        ["Guardado en", ruta2]
+      ])
+    ].join("\n")
+  );
+  if (ctx.ent.env.OPENFACTURA_API_KEY) {
+    ctx.ent.stderr(
+      "Aviso: OPENFACTURA_API_KEY est\xE1 definida y tiene prioridad sobre la clave guardada."
+    );
+  }
+  return void 0;
+}
+async function logout(ctx) {
+  const config = leerConfig(ctx.ent.env);
+  const habia = ctx.cfg.perfil in config.perfiles;
+  if (habia) {
+    delete config.perfiles[ctx.cfg.perfil];
+    guardarConfig(ctx.ent.env, config);
+  }
+  mostrar(
+    ctx,
+    { perfil: ctx.cfg.perfil, eliminado: habia },
+    () => habia ? `Sesi\xF3n cerrada: se borr\xF3 la clave del perfil \xAB${ctx.cfg.perfil}\xBB (${rutaConfig(ctx.ent.env)}).` : `No hab\xEDa una sesi\xF3n guardada en el perfil \xAB${ctx.cfg.perfil}\xBB.`
+  );
+  if (ctx.ent.env.OPENFACTURA_API_KEY) {
+    ctx.ent.stderr("Aviso: OPENFACTURA_API_KEY sigue definida en el entorno.");
+  }
+  return void 0;
+}
+async function whoami(ctx) {
+  const { datos } = await ctx.api().pedir("GET", "/yo");
+  const usuario = datos.usuario;
+  mostrar(
+    ctx,
+    datos,
+    () => fichas([
+      ["Actor", datos.actor],
+      ["Usuario", usuario ? `${usuario.nombre} <${usuario.correo}>` : null],
+      ["Rol", datos.rol],
+      ["Organizaci\xF3n", datos.organizationId],
+      [
+        "Ambiente",
+        `${nombreAmbiente(datos.ambiente)}${datos.simulador ? " (simulador del MH)" : ""}`
+      ],
+      ["Servidor", `${ctx.cfg.url} (${ctx.cfg.origenUrl})`],
+      ["Clave", `${enmascarar(ctx.cfg.apiKey)} (${ctx.cfg.origenClave})`],
+      ["Perfil", ctx.cfg.perfil],
+      ["Permisos", Array.isArray(datos.permisos) ? datos.permisos.join(", ") : null]
+    ])
+  );
+  return void 0;
+}
+async function emisor(ctx) {
+  const { datos } = await ctx.api().pedir("GET", "/emisor");
+  mostrar(ctx, datos, () => {
+    const e = datos.emisor;
+    if (!e) return "El emisor a\xFAn no est\xE1 configurado. Complete sus datos en el panel web.";
+    const establecimientos = datos.establecimientos ?? [];
+    const credenciales = datos.credenciales ?? {};
+    return [
+      fichas([
+        ["Nombre", e.nombre],
+        ["Nombre comercial", e.nombreComercial],
+        ["NIT", e.nit],
+        ["NRC", e.nrc],
+        ["Actividad", `${e.codActividad} ${e.descActividad}`],
+        [
+          "Direcci\xF3n",
+          `${e.complemento} (depto. ${e.departamento}, mun. ${e.municipio}, dist. ${e.distrito})`
+        ],
+        ["Tel\xE9fono", e.telefono],
+        ["Correo", e.correo],
+        ["Ambiente activo", nombreAmbiente(datos.ambienteActivo)]
+      ]),
+      "",
+      "Establecimientos",
+      tabla(
+        ["c\xF3digo", "nombre", "tipo", "puntos de venta"],
+        establecimientos.map((est) => [
+          est.codMh,
+          est.nombre,
+          est.tipo,
+          (est.puntosVenta ?? []).map((pv) => `${pv.codMh} ${pv.nombre}`).join(", ")
+        ])
+      ),
+      "",
+      "Credenciales del MH",
+      tabla(
+        ["ambiente", "contrase\xF1a api", "certificado", "nit del certificado"],
+        Object.entries(credenciales).map(([ambiente, c]) => [
+          nombreAmbiente(ambiente),
+          siNo(c.apiPassword),
+          siNo(c.certificado),
+          c.certificadoNit
+        ])
+      )
+    ].join("\n");
+  });
+  return void 0;
+}
+async function catalogos(ctx) {
+  const id = ctx.args[0];
+  if (!id) {
+    if (ctx.op("q") !== void 0 || ctx.op("departamento") !== void 0) {
+      throw new ErrorUso(
+        "--q y --departamento requieren el id del cat\xE1logo, por ejemplo: openfactura catalogos CAT-013 --departamento 06"
+      );
+    }
+    const { datos: datos2 } = await ctx.api().pedir("GET", "/catalogos");
+    mostrar(
+      ctx,
+      datos2,
+      () => tabla(
+        ["id", "nombre", "valores"],
+        datos2.map((c) => [c.id, c.nombre, c.total]),
+        [2]
+      )
+    );
+    return void 0;
+  }
+  const { datos } = await ctx.api().pedir("GET", `/catalogos/${segmento(id.toUpperCase())}`, {
+    query: { q: ctx.op("q"), departamento: ctx.op("departamento") }
+  });
+  mostrar(ctx, datos, () => {
+    const conDepartamento = datos.valores.some((v) => v.departamento);
+    const filas = datos.valores.map(
+      (v) => conDepartamento ? [v.codigo, v.valor, v.departamento] : [v.codigo, v.valor]
+    );
+    return [
+      `${datos.id} ${datos.nombre} \u2014 ${datos.valores.length} de ${datos.total} valores`,
+      tabla(conDepartamento ? ["c\xF3digo", "valor", "departamento"] : ["c\xF3digo", "valor"], filas)
+    ].join("\n");
+  });
+  return void 0;
+}
+async function clientesList(ctx) {
+  const { datos } = await ctx.api().pedir("GET", "/clientes", { query: { q: ctx.op("q") } });
+  mostrar(
+    ctx,
+    datos,
+    () => datos.length ? tabla(
+      ["id", "doc", "n\xFAmero", "nombre", "nrc", "correo"],
+      datos.map((c) => [c.id, c.tipoDocumento, c.numDocumento, c.nombre, c.nrc, c.correo])
+    ) : "No hay clientes."
+  );
+  return void 0;
+}
+async function clientesAdd(ctx) {
+  const cuerpo = await cuerpoDeAlta(ctx, CAMPOS_CLIENTE);
+  const { datos } = await ctx.api().pedir("POST", "/clientes", { cuerpo });
+  mostrar(
+    ctx,
+    datos,
+    () => [
+      "Cliente creado.",
+      fichas([
+        ["Id", datos.id],
+        ["Documento", `${datos.tipoDocumento} ${datos.numDocumento}`],
+        ["Nombre", datos.nombre],
+        ["NRC", datos.nrc],
+        ["Correo", datos.correo]
+      ])
+    ].join("\n")
+  );
+  return void 0;
+}
+async function productosList(ctx) {
+  const { datos } = await ctx.api().pedir("GET", "/productos", { query: { q: ctx.op("q") } });
+  mostrar(
+    ctx,
+    datos,
+    () => datos.length ? tabla(
+      ["id", "c\xF3digo", "descripci\xF3n", "precio sin iva", "\xEDtem", "unidad", "venta"],
+      datos.map((p) => [
+        p.id,
+        p.codigo,
+        p.descripcion,
+        dinero(p.precioUnitario),
+        p.tipoItem,
+        p.uniMedida,
+        p.tipoVenta
+      ]),
+      [3]
+    ) : "No hay productos."
+  );
+  return void 0;
+}
+async function productosAdd(ctx) {
+  const cuerpo = await cuerpoDeAlta(ctx, CAMPOS_PRODUCTO, ["precio", "tipo-item", "uni-medida"]);
+  const { datos } = await ctx.api().pedir("POST", "/productos", { cuerpo });
+  mostrar(
+    ctx,
+    datos,
+    () => [
+      "Producto creado.",
+      fichas([
+        ["Id", datos.id],
+        ["C\xF3digo", datos.codigo],
+        ["Descripci\xF3n", datos.descripcion],
+        ["Precio sin IVA", dinero(datos.precioUnitario)],
+        ["Tipo de venta", datos.tipoVenta]
+      ])
+    ].join("\n")
+  );
+  return void 0;
+}
+async function dteValidar(ctx) {
+  const cuerpo = await leerEmision(ctx, ctx.args[0]);
+  const { datos } = await ctx.api().pedir("POST", "/dte/validar", { cuerpo });
+  const problemas = datos.problemas ?? [];
+  mostrar(ctx, datos, () => {
+    const resumen = datos.dte?.resumen ?? {};
+    const numero = (campo) => typeof resumen[campo] === "number" ? dinero(resumen[campo]) : null;
+    return [
+      fichas([
+        ["Tipo", nombreTipo(cuerpo.tipoDte)],
+        ["Receptor", datos.receptorNombre],
+        ["Gravado", numero("totalGravada")],
+        ["Exento", numero("totalExenta")],
+        ["No sujeto", numero("totalNoSuj")],
+        ["IVA", numero("totalIva")],
+        ["Total", dinero(datos.total)],
+        ["En letras", resumen.totalLetras]
+      ]),
+      "",
+      problemas.length ? [
+        `${problemas.length} problema(s):`,
+        ...problemas.map((p) => `  ${p.ruta}: ${p.mensaje}`)
+      ].join("\n") : "V\xE1lido: cumple el esquema del MH. No se emiti\xF3 nada."
+    ].join("\n");
+  });
+  return problemas.length ? SALIDA.error : SALIDA.ok;
+}
+async function enviarUnaVez(ctx, ruta2, cuerpo, qu\u00E9, reintento, stdin = false) {
+  const api = ctx.api();
+  const clave = ctx.op("idempotency-key") ?? randomUUID();
+  if (clave.length < 1 || clave.length > 200)
+    throw new ErrorUso("--idempotency-key debe tener entre 1 y 200 caracteres.");
+  await confirmar(ctx, qu\u00E9, stdin);
+  ctx.ent.stderr(`Idempotency-Key: ${clave}`);
+  try {
+    const respuesta = await api.pedir("POST", ruta2, {
+      cuerpo,
+      headers: { "Idempotency-Key": clave }
+    });
+    if (respuesta.headers.get("Idempotent-Replayed") === "true") {
+      ctx.ent.stderr(
+        "Respuesta repetida: esta Idempotency-Key ya se hab\xEDa usado; no se transmiti\xF3 de nuevo."
+      );
+    }
+    return respuesta.datos;
+  } catch (error) {
+    if (error instanceof ErrorCli && (error.code === "sin_conexion" || error.code === "tiempo_agotado")) {
+      ctx.ent.stderr(
+        `No se sabe si se transmiti\xF3. Reintente con la misma clave para no duplicarlo:
+  openfactura ${reintento} --idempotency-key ${clave}`
+      );
+    }
+    throw error;
+  }
+}
+async function dteEmitir(ctx) {
+  const origen = ctx.args[0];
+  const cuerpo = await leerEmision(ctx, origen);
+  const doc = await enviarUnaVez(
+    ctx,
+    "/dte",
+    cuerpo,
+    `emitir un DTE (${nombreTipo(cuerpo.tipoDte)})`,
+    `dte emitir ${origen}`,
+    origen === "-"
+  );
+  if (doc.estado === "contingencia") {
+    ctx.ent.stderr(
+      "El MH no respondi\xF3: el DTE qued\xF3 firmado en contingencia. Transm\xEDtalo con `openfactura contingencia transmitir`."
+    );
+  }
+  mostrar(ctx, doc, () => fichaDocumento(doc));
+  return void 0;
+}
+async function dteList(ctx) {
+  const estado = ctx.op("estado");
+  if (estado !== void 0 && !ESTADOS_DTE.includes(estado)) {
+    throw new ErrorUso(`--estado debe ser uno de: ${ESTADOS_DTE.join(", ")}`);
+  }
+  for (const opcion of ["desde", "hasta"]) {
+    const valor = ctx.op(opcion);
+    if (valor !== void 0 && !/^\d{4}-\d{2}-\d{2}$/.test(valor))
+      throw new ErrorUso(`--${opcion} debe tener el formato AAAA-MM-DD`);
+  }
+  const { datos } = await ctx.api().pedir("GET", "/dte", {
+    query: {
+      tipo: ctx.op("tipo"),
+      estado,
+      q: ctx.op("q"),
+      desde: ctx.op("desde"),
+      hasta: ctx.op("hasta"),
+      pagina: entero(ctx, "pagina")
+    }
+  });
+  mostrar(
+    ctx,
+    datos,
+    () => [
+      datos.items.length ? tabla(
+        [
+          "fecha",
+          "tipo",
+          "n\xFAmero de control",
+          "estado",
+          "receptor",
+          "total",
+          "c\xF3digo de generaci\xF3n"
+        ],
+        datos.items.map((d) => [
+          d.fechaEmision,
+          d.tipoDte,
+          d.numeroControl,
+          d.estado,
+          d.receptorNombre,
+          dinero(d.total),
+          d.codigoGeneracion
+        ]),
+        [5]
+      ) : "No hay documentos.",
+      `P\xE1gina ${datos.pagina} \xB7 ${datos.items.length} de ${datos.total} documento(s) \xB7 ambiente ${nombreAmbiente(datos.ambiente)}`
+    ].join("\n")
+  );
+  return void 0;
+}
+async function dteGet(ctx) {
+  const { datos } = await ctx.api().pedir("GET", `/dte/${segmento(ctx.args[0])}`);
+  mostrar(ctx, datos, () => {
+    const mh = datos.respuestaMh;
+    const eventos = datos.eventos ?? [];
+    const observaciones = Array.isArray(mh?.observaciones) ? mh.observaciones.join("; ") : null;
+    return [
+      fichaDocumento(datos),
+      ...mh ? [
+        "",
+        "Respuesta del MH",
+        fichas([
+          ["Estado", mh.estado],
+          ["Mensaje", `${mh.codigoMsg ?? ""} ${mh.descripcionMsg ?? ""}`.trim()],
+          ["Procesado", mh.fhProcesamiento],
+          ["Observaciones", observaciones]
+        ])
+      ] : [],
+      ...eventos.length ? [
+        "",
+        "Eventos",
+        tabla(
+          ["tipo", "estado", "fecha (UTC)", "c\xF3digo de generaci\xF3n", "sello"],
+          eventos.map((e) => [
+            e.tipo,
+            e.estado,
+            fecha2(e.creado),
+            e.codigoGeneracion,
+            e.selloRecibido
+          ])
+        )
+      ] : []
+    ].join("\n");
+  });
+  return void 0;
+}
+async function dteJson(ctx) {
+  const { datos } = await ctx.api().pedir("GET", `/dte/${segmento(ctx.args[0])}/json`);
+  const texto2 = JSON.stringify(datos, null, 2);
+  const salida = ctx.op("output");
+  if (salida === void 0) {
+    ctx.ent.stdout(texto2);
+    return void 0;
+  }
+  const destino = resolve(ctx.ent.cwd, salida);
+  await writeFile(destino, `${texto2}
+`);
+  mostrar(ctx, { archivo: destino }, () => `JSON guardado en ${destino}`);
+  return void 0;
+}
+async function dtePdf(ctx) {
+  const codigo = ctx.args[0];
+  const bytes = await ctx.api().descargar(`/dte/${segmento(codigo)}/pdf`);
+  const destino = resolve(ctx.ent.cwd, ctx.op("output") ?? `${basename(codigo)}.pdf`);
+  await writeFile(destino, bytes);
+  mostrar(
+    ctx,
+    { archivo: destino, bytes: bytes.length },
+    () => `PDF guardado en ${destino} (${bytes.length} bytes)`
+  );
+  return void 0;
+}
+async function dteInvalidar(ctx) {
+  const codigo = ctx.args[0];
+  const tipo = ctx.op("tipo");
+  if (tipo !== "1" && tipo !== "2" && tipo !== "3") {
+    throw new ErrorUso(
+      "Indique --tipo 1|2|3 (1 error en la informaci\xF3n, 2 rescindir la operaci\xF3n, 3 otro)."
+    );
+  }
+  const cuerpo = { tipoAnulacion: Number(tipo) };
+  if (ctx.op("motivo") !== void 0) cuerpo.motivoAnulacion = ctx.op("motivo");
+  if (ctx.op("reemplazo") !== void 0) cuerpo.codigoGeneracionReemplazo = ctx.op("reemplazo");
+  const api = ctx.api();
+  await confirmar(ctx, `invalidar el DTE ${codigo} (irreversible)`);
+  const { datos } = await api.pedir("POST", `/dte/${segmento(codigo)}/invalidar`, {
+    cuerpo
+  });
+  mostrar(ctx, datos, () => `DTE invalidado.
+${fichaDocumento(datos)}`);
+  return void 0;
+}
+var TIPOS_EVENTO = ["retorno", "operaciones_especiales"];
+function fichaEvento(e) {
+  return fichas([
+    [
+      "Evento",
+      e.tipoEvento === "18" ? "18 Retorno" : e.tipoEvento === "17" ? "17 Operaciones especiales" : e.tipo
+    ],
+    ["Estado", e.estado],
+    ["C\xF3digo de generaci\xF3n", e.codigoGeneracion],
+    ["Ambiente", nombreAmbiente(e.ambiente)],
+    ["Sello recibido", e.selloRecibido]
+  ]);
+}
+async function leerObjeto(ctx, origen, forma) {
+  const cuerpo = await leerJson(ctx, origen);
+  if (!cuerpo || typeof cuerpo !== "object" || Array.isArray(cuerpo) || !("items" in cuerpo)) {
+    throw new ErrorUso(`El archivo debe ser un objeto ${forma}`);
+  }
+  return cuerpo;
+}
+async function dteRetorno(ctx) {
+  const [codigo, origen] = ctx.args;
+  const cuerpo = await leerObjeto(
+    ctx,
+    origen,
+    '{ "items": [{ "descripcion", "cantidad", "precioUni" }] }'
+  );
+  const evento = await enviarUnaVez(
+    ctx,
+    `/dte/${segmento(codigo)}/retorno`,
+    cuerpo,
+    `registrar un retorno sobre el DTE ${codigo}`,
+    `dte retorno ${codigo} ${origen}`,
+    origen === "-"
+  );
+  mostrar(ctx, evento, () => `Retorno registrado.
+${fichaEvento(evento)}`);
+  return void 0;
+}
+async function eventosOperacionesEspeciales(ctx) {
+  const origen = ctx.args[0];
+  const cuerpo = await leerObjeto(
+    ctx,
+    origen,
+    '{ "tipoDocumento": "02" | "97", "fecha"?, "items": [{ "descripcion", "precioUni", "docDel", "docAl" }] }'
+  );
+  const evento = await enviarUnaVez(
+    ctx,
+    "/eventos/operaciones-especiales",
+    cuerpo,
+    "informar operaciones especiales",
+    `eventos operaciones-especiales ${origen}`,
+    origen === "-"
+  );
+  mostrar(ctx, evento, () => `Operaciones especiales informadas.
+${fichaEvento(evento)}`);
+  return void 0;
+}
+async function eventosList(ctx) {
+  const tipo = ctx.op("tipo");
+  if (tipo !== void 0 && !TIPOS_EVENTO.includes(tipo)) {
+    throw new ErrorUso(`--tipo debe ser uno de: ${TIPOS_EVENTO.join(", ")}`);
+  }
+  const { datos } = await ctx.api().pedir("GET", "/eventos", { query: { tipo } });
+  mostrar(
+    ctx,
+    datos,
+    () => datos.length ? tabla(
+      ["creado", "evento", "estado", "c\xF3digo de generaci\xF3n"],
+      datos.map((e) => [
+        new Date(e.creado).toISOString().slice(0, 10),
+        e.tipoEvento,
+        e.estado,
+        e.codigoGeneracion
+      ])
+    ) : "No hay eventos."
+  );
+  return void 0;
+}
+async function eventosGet(ctx) {
+  const { datos } = await ctx.api().pedir("GET", `/eventos/${segmento(ctx.args[0])}`);
+  mostrar(ctx, datos, () => fichaEvento(datos));
+  return void 0;
+}
+async function eventosJson(ctx) {
+  const codigo = ctx.args[0];
+  const { datos } = await ctx.api().pedir("GET", `/eventos/${segmento(codigo)}/json`);
+  const texto2 = JSON.stringify(datos, null, 2);
+  const salida = ctx.op("output");
+  if (salida === void 0) {
+    ctx.ent.stdout(texto2);
+    return void 0;
+  }
+  const destino = resolve(ctx.ent.cwd, salida);
+  await writeFile(destino, `${texto2}
+`);
+  mostrar(ctx, { archivo: destino }, () => `JSON guardado en ${destino}`);
+  return void 0;
+}
+async function eventosPdf(ctx) {
+  const codigo = ctx.args[0];
+  const bytes = await ctx.api().descargar(`/eventos/${segmento(codigo)}/pdf`);
+  const destino = resolve(ctx.ent.cwd, ctx.op("output") ?? `${basename(codigo)}.pdf`);
+  await writeFile(destino, bytes);
+  mostrar(
+    ctx,
+    { archivo: destino, bytes: bytes.length },
+    () => `PDF guardado en ${destino} (${bytes.length} bytes)`
+  );
+  return void 0;
+}
+async function contingenciaTransmitir(ctx) {
+  const api = ctx.api();
+  await confirmar(ctx, "transmitir los DTE en contingencia");
+  const { datos } = await api.pedir("POST", "/contingencia/transmitir");
+  mostrar(ctx, datos, () => {
+    const procesados = datos.procesados ?? [];
+    const rechazados = datos.rechazados ?? [];
+    if (!datos.evento && !procesados.length && !rechazados.length)
+      return "No hay documentos en contingencia.";
+    const linea = (d) => `  ${typeof d === "string" ? d : JSON.stringify(d)}`;
+    return [
+      fichas([
+        ["Procesados", procesados.length],
+        ["Rechazados", rechazados.length],
+        ["Restantes", datos.restantes]
+      ]),
+      ...rechazados.length ? ["", "Rechazados:", ...rechazados.map(linea)] : []
+    ].join("\n");
+  });
+  return void 0;
+}
+function fichaWebhook(w) {
+  return fichas([
+    ["Id", w.id],
+    ["URL", w.url],
+    ["Descripci\xF3n", w.descripcion],
+    ["Eventos", Array.isArray(w.eventos) ? w.eventos.join(", ") : null],
+    ["Activo", siNo(w.activo)]
+  ]);
+}
+function mostrarSecreto(ctx, w, titulo) {
+  mostrar(
+    ctx,
+    w,
+    () => [
+      titulo,
+      fichaWebhook(w),
+      "",
+      `Secreto de firma: ${w.secreto}`,
+      "Gu\xE1rdelo ahora: no se vuelve a mostrar. Verifique con \xE9l la cabecera OpenFactura-Signature."
+    ].join("\n")
+  );
+}
+async function webhooksList(ctx) {
+  const { datos } = await ctx.api().pedir("GET", "/webhooks");
+  mostrar(
+    ctx,
+    datos,
+    () => datos.length ? tabla(
+      ["id", "url", "eventos", "activo", "descripci\xF3n"],
+      datos.map((w) => [
+        w.id,
+        w.url,
+        w.eventos.join(", "),
+        siNo(w.activo),
+        w.descripcion
+      ])
+    ) : "No hay webhooks."
+  );
+  return void 0;
+}
+async function webhooksAdd(ctx) {
+  const texto2 = ctx.op("eventos");
+  const eventos = texto2 ? texto2.split(",").map((e) => e.trim()).filter(Boolean) : [...EVENTOS_WEBHOOK];
+  const desconocido = eventos.find((e) => !EVENTOS_WEBHOOK.includes(e));
+  if (desconocido || !eventos.length) {
+    throw new ErrorUso(`--eventos acepta, separados por coma: ${EVENTOS_WEBHOOK.join(", ")}`);
+  }
+  const cuerpo = { url: ctx.args[0], eventos };
+  if (ctx.op("descripcion") !== void 0) cuerpo.descripcion = ctx.op("descripcion");
+  const { datos } = await ctx.api().pedir("POST", "/webhooks", { cuerpo });
+  mostrarSecreto(ctx, datos, "Webhook creado.");
+  return void 0;
+}
+async function webhooksRemove(ctx) {
+  const id = ctx.args[0];
+  const { datos } = await ctx.api().pedir("DELETE", `/webhooks/${segmento(id)}`);
+  mostrar(ctx, datos, () => `Webhook ${id} eliminado.`);
+  return void 0;
+}
+async function webhooksTest(ctx) {
+  const id = ctx.args[0];
+  const { datos } = await ctx.api().pedir("POST", `/webhooks/${segmento(id)}/probar`);
+  mostrar(
+    ctx,
+    datos,
+    () => datos.entregado ? `Entregado: el destino respondi\xF3 HTTP ${datos.status}.` : `No se entreg\xF3: ${datos.error ?? "error desconocido"}.`
+  );
+  return datos.entregado ? SALIDA.ok : SALIDA.error;
+}
+async function webhooksDeliveries(ctx) {
+  const id = ctx.args[0];
+  const { datos } = await ctx.api().pedir("GET", `/webhooks/${segmento(id)}/entregas`);
+  mostrar(
+    ctx,
+    datos,
+    () => datos.length ? tabla(
+      [
+        "creado (UTC)",
+        "evento",
+        "estado",
+        "intentos",
+        "http",
+        "error",
+        "pr\xF3ximo intento",
+        "id"
+      ],
+      datos.map((e) => [
+        fecha2(e.creado),
+        e.evento,
+        e.estado,
+        e.intentos,
+        e.ultimoStatus,
+        e.ultimoError,
+        fecha2(e.proximoIntento),
+        e.id
+      ]),
+      [3]
+    ) : "Este webhook todav\xEDa no tiene entregas."
+  );
+  return void 0;
+}
+async function webhooksRotate(ctx) {
+  const id = ctx.args[0];
+  const { datos } = await ctx.api().pedir("POST", `/webhooks/${segmento(id)}/rotar-secreto`);
+  mostrarSecreto(ctx, datos, "Secreto rotado: el anterior ya no firma.");
+  return void 0;
+}
+async function mcp(ctx) {
+  const api = ctx.api();
+  ctx.ent.stderr(
+    `openfactura mcp: servidor MCP por stdio \u2192 ${ctx.cfg.url} (clave ${enmascarar(ctx.cfg.apiKey)})`
+  );
+  await servirMcp(api, ctx.version);
+  return void 0;
+}
+var GRUPOS = {
+  clientes: "Clientes guardados",
+  productos: "Productos y servicios guardados",
+  dte: "Documentos tributarios electr\xF3nicos",
+  eventos: "Eventos de retorno (18) y de operaciones especiales (17)",
+  contingencia: "Documentos emitidos en contingencia",
+  webhooks: "Notificaciones firmadas a su sistema cuando cambia un documento"
+};
+var COMANDOS = [
+  {
+    nombre: "login",
+    uso: "login [--url <url>] [--key <clave>]",
+    resumen: "Verifica una clave de API y la guarda",
+    opciones: ["key"],
+    args: [0, 0],
+    accion: login
+  },
+  {
+    nombre: "logout",
+    uso: "logout",
+    resumen: "Borra la clave guardada del perfil",
+    opciones: [],
+    args: [0, 0],
+    accion: logout
+  },
+  {
+    nombre: "whoami",
+    uso: "whoami",
+    resumen: "Muestra el actor, sus permisos, el ambiente y el servidor",
+    opciones: [],
+    args: [0, 0],
+    accion: whoami
+  },
+  {
+    nombre: "emisor",
+    uso: "emisor",
+    resumen: "Datos del emisor, establecimientos y credenciales cargadas",
+    opciones: [],
+    args: [0, 0],
+    accion: emisor
+  },
+  {
+    nombre: "clientes list",
+    uso: "clientes list [--q <texto>]",
+    resumen: "Lista o busca clientes",
+    opciones: ["q"],
+    args: [0, 0],
+    accion: clientesList
+  },
+  {
+    nombre: "clientes add",
+    uso: "clientes add --file <cliente.json> | --tipo-documento <36|13|03|02|37> --num-documento <n> --nombre <nombre> [\u2026]",
+    resumen: "Crea un cliente",
+    opciones: ["file", ...Object.keys(CAMPOS_CLIENTE)],
+    args: [0, 0],
+    accion: clientesAdd
+  },
+  {
+    nombre: "productos list",
+    uso: "productos list [--q <texto>]",
+    resumen: "Lista o busca productos",
+    opciones: ["q"],
+    args: [0, 0],
+    accion: productosList
+  },
+  {
+    nombre: "productos add",
+    uso: "productos add --file <producto.json> | --codigo <c> --descripcion <d> --precio <sin IVA> [\u2026]",
+    resumen: "Crea un producto o servicio",
+    opciones: ["file", ...Object.keys(CAMPOS_PRODUCTO)],
+    args: [0, 0],
+    accion: productosAdd
+  },
+  {
+    nombre: "catalogos",
+    uso: "catalogos [<id>] [--q <texto>] [--departamento <06>]",
+    resumen: "Cat\xE1logos oficiales del MH (CAT-012, CAT-019\u2026)",
+    opciones: ["q", "departamento"],
+    args: [0, 1],
+    accion: catalogos
+  },
+  {
+    nombre: "dte validar",
+    uso: "dte validar <archivo.json | ->",
+    resumen: "Valida un DTE sin emitirlo (salida 1 si hay problemas)",
+    opciones: [],
+    args: [1, 1],
+    accion: dteValidar
+  },
+  {
+    nombre: "dte emitir",
+    uso: "dte emitir <archivo.json | -> [--idempotency-key <k>] [--yes]",
+    resumen: "Emite un DTE: lo firma y lo transmite al MH",
+    opciones: ["idempotency-key", "yes"],
+    args: [1, 1],
+    accion: dteEmitir
+  },
+  {
+    nombre: "dte list",
+    uso: "dte list [--tipo <01>] [--estado <estado>] [--q <texto>] [--desde <AAAA-MM-DD>] [--hasta <AAAA-MM-DD>] [--pagina <n>]",
+    resumen: "Lista documentos, del m\xE1s reciente al m\xE1s antiguo",
+    opciones: ["tipo", "estado", "q", "desde", "hasta", "pagina"],
+    args: [0, 0],
+    accion: dteList
+  },
+  {
+    nombre: "dte get",
+    uso: "dte get <codigoGeneracion>",
+    resumen: "Detalle de un documento",
+    opciones: [],
+    args: [1, 1],
+    accion: dteGet
+  },
+  {
+    nombre: "dte json",
+    uso: "dte json <codigoGeneracion> [-o <archivo.json>]",
+    resumen: "JSON oficial del DTE (firma y sello)",
+    opciones: ["output"],
+    args: [1, 1],
+    accion: dteJson
+  },
+  {
+    nombre: "dte pdf",
+    uso: "dte pdf <codigoGeneracion> [-o <archivo.pdf>]",
+    resumen: "Descarga la representaci\xF3n gr\xE1fica en PDF",
+    opciones: ["output"],
+    args: [1, 1],
+    accion: dtePdf
+  },
+  {
+    nombre: "dte invalidar",
+    uso: "dte invalidar <codigoGeneracion> --tipo <1|2|3> [--motivo <texto>] [--reemplazo <codigo>] [--yes]",
+    resumen: "Invalida un DTE procesado, o un evento de retorno u operaciones especiales (irreversible)",
+    opciones: ["tipo", "motivo", "reemplazo", "yes"],
+    args: [1, 1],
+    accion: dteInvalidar
+  },
+  {
+    nombre: "dte retorno",
+    uso: "dte retorno <codigoGeneracion> <archivo.json | -> [--idempotency-key <k>] [--yes]",
+    resumen: "Registra un retorno (evento 18) sobre una Factura, Exportaci\xF3n o Sujeto Excluido",
+    opciones: ["idempotency-key", "yes"],
+    args: [2, 2],
+    accion: dteRetorno
+  },
+  {
+    nombre: "eventos operaciones-especiales",
+    uso: "eventos operaciones-especiales <archivo.json | -> [--idempotency-key <k>] [--yes]",
+    resumen: "Informa facturas simplificadas o comprobantes de control interno (evento 17)",
+    opciones: ["idempotency-key", "yes"],
+    args: [1, 1],
+    accion: eventosOperacionesEspeciales
+  },
+  {
+    nombre: "eventos list",
+    uso: "eventos list [--tipo retorno|operaciones_especiales]",
+    resumen: "Lista los eventos de retorno y operaciones especiales",
+    opciones: ["tipo"],
+    args: [0, 0],
+    accion: eventosList
+  },
+  {
+    nombre: "eventos get",
+    uso: "eventos get <codigoGeneracion>",
+    resumen: "Muestra un evento",
+    opciones: [],
+    args: [1, 1],
+    accion: eventosGet
+  },
+  {
+    nombre: "eventos json",
+    uso: "eventos json <codigoGeneracion> [-o <archivo.json>]",
+    resumen: "Descarga el archivo JSON oficial del evento",
+    opciones: ["output"],
+    args: [1, 1],
+    accion: eventosJson
+  },
+  {
+    nombre: "eventos pdf",
+    uso: "eventos pdf <codigoGeneracion> [-o <archivo.pdf>]",
+    resumen: "Descarga la representaci\xF3n gr\xE1fica del evento",
+    opciones: ["output"],
+    args: [1, 1],
+    accion: eventosPdf
+  },
+  {
+    nombre: "contingencia transmitir",
+    uso: "contingencia transmitir [--yes]",
+    resumen: "Transmite al MH los DTE en contingencia",
+    opciones: ["yes"],
+    args: [0, 0],
+    accion: contingenciaTransmitir
+  },
+  {
+    nombre: "webhooks list",
+    uso: "webhooks list",
+    resumen: "Lista los webhooks (sin su secreto)",
+    opciones: [],
+    args: [0, 0],
+    accion: webhooksList
+  },
+  {
+    nombre: "webhooks add",
+    uso: "webhooks add <https://url> [--eventos <e1,e2>] [--descripcion <texto>]",
+    resumen: "Crea un webhook y muestra su secreto de firma una sola vez",
+    opciones: ["eventos", "descripcion"],
+    args: [1, 1],
+    accion: webhooksAdd
+  },
+  {
+    nombre: "webhooks remove",
+    uso: "webhooks remove <id>",
+    resumen: "Elimina un webhook y su historial de entregas",
+    opciones: [],
+    args: [1, 1],
+    accion: webhooksRemove
+  },
+  {
+    nombre: "webhooks test",
+    uso: "webhooks test <id>",
+    resumen: "Env\xEDa un evento webhook.prueba (salida 1 si no se entrega)",
+    opciones: [],
+    args: [1, 1],
+    accion: webhooksTest
+  },
+  {
+    nombre: "webhooks deliveries",
+    uso: "webhooks deliveries <id>",
+    resumen: "\xDAltimas 50 entregas de un webhook",
+    opciones: [],
+    args: [1, 1],
+    accion: webhooksDeliveries
+  },
+  {
+    nombre: "webhooks rotate",
+    uso: "webhooks rotate <id>",
+    resumen: "Genera un secreto de firma nuevo y lo muestra una vez",
+    opciones: [],
+    args: [1, 1],
+    accion: webhooksRotate
+  },
+  {
+    nombre: "mcp",
+    uso: "mcp",
+    resumen: "Servidor MCP por stdio para Claude y otros clientes",
+    opciones: [],
+    args: [0, 0],
+    accion: mcp
+  }
+];
+
+// src/cli.ts
+var VERSION = package_default.version;
+var OPCIONES = {
+  help: { type: "boolean", short: "h", ayuda: "Muestra esta ayuda" },
+  version: { type: "boolean", short: "v", ayuda: "Muestra la versi\xF3n" },
+  json: { type: "boolean", ayuda: "Imprime el JSON de la API (para scripts)" },
+  url: { type: "string", ayuda: "URL del servidor (o OPENFACTURA_URL)" },
+  profile: {
+    type: "string",
+    ayuda: "Perfil de configuraci\xF3n (o OPENFACTURA_PROFILE; por defecto \xABdefault\xBB)"
+  },
+  yes: { type: "boolean", short: "y", ayuda: "No pedir confirmaci\xF3n con claves de producci\xF3n" },
+  key: { type: "string", ayuda: "Clave de API; si se omite, se pide sin mostrarla" },
+  q: { type: "string", ayuda: "Texto a buscar" },
+  file: {
+    type: "string",
+    short: "f",
+    ayuda: "Archivo JSON con los datos (\xAB-\xBB lee la entrada est\xE1ndar)"
+  },
+  output: { type: "string", short: "o", ayuda: "Archivo de salida" },
+  "idempotency-key": {
+    type: "string",
+    ayuda: "Clave de idempotencia; por defecto se genera un UUID"
+  },
+  tipo: {
+    type: "string",
+    ayuda: "Tipo de DTE (01, 03\u2026); al invalidar, tipo de anulaci\xF3n (1, 2, 3); en eventos, retorno | operaciones_especiales"
+  },
+  estado: {
+    type: "string",
+    ayuda: "pendiente | procesado | rechazado | contingencia | invalidado"
+  },
+  desde: { type: "string", ayuda: "Fecha inicial AAAA-MM-DD" },
+  hasta: { type: "string", ayuda: "Fecha final AAAA-MM-DD" },
+  pagina: { type: "string", ayuda: "N\xFAmero de p\xE1gina" },
+  motivo: { type: "string", ayuda: "Motivo de la invalidaci\xF3n" },
+  reemplazo: { type: "string", ayuda: "C\xF3digo de generaci\xF3n del DTE que reemplaza al invalidado" },
+  "tipo-documento": {
+    type: "string",
+    ayuda: "36 NIT | 13 DUI | 03 pasaporte | 02 carn\xE9 de residente | 37 otro"
+  },
+  "num-documento": { type: "string", ayuda: "N\xFAmero del documento" },
+  nrc: { type: "string", ayuda: "NRC del contribuyente" },
+  nombre: { type: "string", ayuda: "Nombre o raz\xF3n social" },
+  "nombre-comercial": { type: "string", ayuda: "Nombre comercial" },
+  "cod-actividad": { type: "string", ayuda: "C\xF3digo de actividad econ\xF3mica (CAT-019)" },
+  "desc-actividad": { type: "string", ayuda: "Descripci\xF3n de la actividad econ\xF3mica" },
+  departamento: { type: "string", ayuda: "C\xF3digo de departamento (CAT-012)" },
+  municipio: { type: "string", ayuda: "C\xF3digo de municipio (CAT-013)" },
+  distrito: { type: "string", ayuda: "C\xF3digo de distrito (CAT-008)" },
+  complemento: { type: "string", ayuda: "Direcci\xF3n" },
+  telefono: { type: "string", ayuda: "Tel\xE9fono" },
+  correo: { type: "string", ayuda: "Correo electr\xF3nico" },
+  codigo: { type: "string", ayuda: "C\xF3digo del producto" },
+  descripcion: { type: "string", ayuda: "Descripci\xF3n (del producto o del webhook)" },
+  eventos: {
+    type: "string",
+    ayuda: "Eventos del webhook separados por coma (por defecto todos): dte.procesado, dte.rechazado, dte.contingencia, dte.invalidado, retorno.procesado, operaciones_especiales.procesado"
+  },
+  precio: { type: "string", ayuda: "Precio unitario SIN IVA" },
+  "tipo-item": {
+    type: "string",
+    ayuda: "1 bien | 2 servicio | 3 ambos | 4 otros tributos (por defecto 1)"
+  },
+  "uni-medida": { type: "string", ayuda: "Unidad de medida, CAT-014 (por defecto 59 = unidad)" },
+  "tipo-venta": { type: "string", ayuda: "gravada | exenta | noSujeta (por defecto gravada)" }
+};
+var GLOBALES = ["help", "json", "url", "profile"];
+var bandera = (nombre) => {
+  const o = OPCIONES[nombre];
+  return `${o.short ? `-${o.short}, ` : ""}--${nombre}${o.type === "string" ? " <valor>" : ""}`;
+};
+var listaOpciones = (nombres) => {
+  const ancho = Math.max(...nombres.map((n) => bandera(n).length));
+  return nombres.map((n) => `  ${bandera(n).padEnd(ancho)}  ${OPCIONES[n].ayuda}`).join("\n");
+};
+function ayudaGeneral(grupo) {
+  const comandos = grupo ? COMANDOS.filter((c) => c.nombre.startsWith(`${grupo} `)) : COMANDOS;
+  const ancho = Math.max(...comandos.map((c) => c.nombre.length));
+  return [
+    grupo ? `openfactura ${grupo} \u2014 ${GRUPOS[grupo]}` : `openfactura ${VERSION} \u2014 facturaci\xF3n electr\xF3nica de El Salvador (DTE) desde la terminal`,
+    "",
+    `Uso: openfactura ${grupo ? `${grupo} <subcomando>` : "<comando>"} [opciones]`,
+    "",
+    "Comandos:",
+    ...comandos.map((c) => `  ${c.nombre.padEnd(ancho)}  ${c.resumen}`),
+    "",
+    "Opciones globales:",
+    listaOpciones(grupo ? GLOBALES : [...GLOBALES, "version"]),
+    "",
+    "Use `openfactura <comando> --help` para ver las opciones de un comando.",
+    ...grupo ? [] : [
+      "",
+      "Entorno: OPENFACTURA_API_KEY, OPENFACTURA_URL, OPENFACTURA_PROFILE.",
+      "Salida: 0 bien \xB7 1 error de la API o de validaci\xF3n \xB7 2 uso incorrecto \xB7 3 sin autenticar \xB7 4 l\xEDmite de peticiones."
+    ]
+  ].join("\n");
+}
+function ayudaComando(comando) {
+  return [
+    comando.resumen,
+    "",
+    `Uso: openfactura ${comando.uso}`,
+    ...comando.opciones.length ? ["", "Opciones:", listaOpciones(comando.opciones)] : [],
+    "",
+    "Opciones globales:",
+    listaOpciones(GLOBALES)
+  ].join("\n");
+}
+function analizar(argv) {
+  try {
+    const opciones = Object.fromEntries(
+      Object.entries(OPCIONES).map(([nombre, { type, short }]) => [
+        nombre,
+        short ? { type, short } : { type }
+      ])
+    );
+    return parseArgs({ args: argv, options: opciones, allowPositionals: true, strict: true });
+  } catch (error) {
+    const { code, message } = error;
+    const opcion = /'(-[^' ]*)/.exec(message)?.[1];
+    if (code === "ERR_PARSE_ARGS_UNKNOWN_OPTION")
+      throw new ErrorUso(`Opci\xF3n desconocida: ${opcion ?? message}`);
+    if (code === "ERR_PARSE_ARGS_INVALID_OPTION_VALUE") {
+      throw new ErrorUso(
+        opcion ? `La opci\xF3n ${opcion} est\xE1 mal usada: revise si lleva o no un valor.` : message
+      );
+    }
+    throw new ErrorUso(message);
+  }
+}
+function informarError(error, ent, json) {
+  if (error instanceof ErrorUso) {
+    ent.stderr(`Error: ${error.message}`);
+    ent.stderr("Use `openfactura --help` para ver los comandos.");
+    return SALIDA.uso;
+  }
+  if (error instanceof ErrorApi) {
+    if (json) {
+      ent.stderr(
+        JSON.stringify(
+          error.retryAfter === null ? error.cuerpo : { ...error.cuerpo, retryAfter: error.retryAfter },
+          null,
+          2
+        )
+      );
+      return error.salida;
+    }
+    ent.stderr(`Error [${error.code}]: ${error.message}`);
+    for (const linea of detalles(error)) ent.stderr(`  ${linea}`);
+    if (error.status === 401)
+      ent.stderr("  Revise OPENFACTURA_API_KEY o ejecute `openfactura login`.");
+    if (error.status === 429) {
+      ent.stderr(
+        `  Retry-After: ${error.retryAfter ?? "?"} (segundos que debe esperar antes de reintentar)`
+      );
+    }
+    return error.salida;
+  }
+  if (error instanceof ErrorCli) {
+    ent.stderr(
+      json ? JSON.stringify(error.cuerpo, null, 2) : `Error [${error.code}]: ${error.message}`
+    );
+    return error.salida;
+  }
+  ent.stderr(
+    `Error inesperado: ${error instanceof Error ? error.stack ?? error.message : String(error)}`
+  );
+  return SALIDA.error;
+}
+function detalles(error) {
+  const d = error.details;
+  if (d === void 0 || d === null) return [];
+  const problema = (p) => `${p.ruta || "(ra\xEDz)"}: ${p.mensaje}`;
+  if (Array.isArray(d)) return d.map((p) => problema(p));
+  if (Array.isArray(d.problemas)) return d.problemas.map((p) => problema(p));
+  if (d.mh && typeof d.mh === "object") {
+    const mh = d.mh;
+    const observaciones = Array.isArray(mh.observaciones) ? mh.observaciones : [];
+    return [
+      `MH ${mh.codigo ?? ""}: ${mh.mensaje ?? ""}`.trim(),
+      ...observaciones.map((o) => `- ${o}`)
+    ];
+  }
+  if (typeof d.permiso === "string") return [`Permiso que falta en la clave: ${d.permiso}`];
+  return [JSON.stringify(d)];
+}
+async function ejecutar(argv, ent) {
+  let json = argv.includes("--json");
+  try {
+    const { values, positionals } = analizar(argv);
+    const valores = values;
+    json = valores.json === true;
+    const [primero, segundo] = positionals;
+    if (!primero) {
+      if (valores.version) {
+        ent.stdout(VERSION);
+        return SALIDA.ok;
+      }
+      if (valores.help) {
+        ent.stdout(ayudaGeneral());
+        return SALIDA.ok;
+      }
+      throw new ErrorUso("Falta el comando.");
+    }
+    const esGrupo = Object.hasOwn(GRUPOS, primero);
+    const nombre = esGrupo ? `${primero} ${segundo ?? ""}`.trim() : primero;
+    const comando = COMANDOS.find((c) => c.nombre === nombre);
+    if (!comando) {
+      if (esGrupo && !segundo && valores.help) {
+        ent.stdout(ayudaGeneral(primero));
+        return SALIDA.ok;
+      }
+      const disponibles = COMANDOS.filter((c) => c.nombre.startsWith(`${primero} `)).map(
+        (c) => c.nombre.split(" ")[1]
+      );
+      throw new ErrorUso(
+        esGrupo ? `${segundo ? `Subcomando desconocido: ${primero} ${segundo}.` : `Falta el subcomando de \xAB${primero}\xBB.`} Disponibles: ${disponibles.join(", ")}` : `Comando desconocido: ${primero}`
+      );
+    }
+    if (valores.help) {
+      ent.stdout(ayudaComando(comando));
+      return SALIDA.ok;
+    }
+    const permitidas = /* @__PURE__ */ new Set([...GLOBALES, ...comando.opciones]);
+    const sobrante = Object.keys(valores).find((opcion) => !permitidas.has(opcion));
+    if (sobrante)
+      throw new ErrorUso(
+        `La opci\xF3n --${sobrante} no aplica a \xAB${comando.nombre}\xBB.
+Uso: openfactura ${comando.uso}`
+      );
+    const args = positionals.slice(esGrupo ? 2 : 1);
+    const [minimo, maximo] = comando.args;
+    if (args.length < minimo || args.length > maximo) {
+      throw new ErrorUso(
+        `${args.length < minimo ? "Faltan argumentos" : `Sobran argumentos (${args.slice(maximo).join(" ")})`}.
+Uso: openfactura ${comando.uso}`
+      );
+    }
+    const cfg = resolver(ent.env, {
+      url: valores.url,
+      perfil: valores.profile
+    });
+    let cliente2;
+    const ctx = {
+      ent,
+      version: VERSION,
+      args,
+      json,
+      si: valores.yes === true,
+      cfg,
+      op: (opcion) => typeof valores[opcion] === "string" ? valores[opcion] : void 0,
+      api: () => {
+        if (!cfg.apiKey) {
+          throw new ErrorCli(
+            "No hay una clave de API. Ejecute `openfactura login` o defina OPENFACTURA_API_KEY.",
+            "no_autenticado",
+            SALIDA.noAutenticado
+          );
+        }
+        if (!cliente2) {
+          const { protocol, hostname } = new URL(cfg.url);
+          if (protocol === "http:" && !["localhost", "127.0.0.1", "[::1]"].includes(hostname)) {
+            ent.stderr(`Aviso: ${cfg.url} no usa HTTPS; la clave de API viaja sin cifrar.`);
+          }
+          cliente2 = new ClienteApi({
+            url: cfg.url,
+            apiKey: cfg.apiKey,
+            version: VERSION,
+            fetch: ent.fetch
+          });
+        }
+        return cliente2;
+      }
+    };
+    return await comando.accion(ctx) ?? SALIDA.ok;
+  } catch (error) {
+    return informarError(error, ent, json);
+  }
+}
+
+// src/index.ts
+async function leerEntrada() {
+  const partes = [];
+  for await (const parte of process.stdin) partes.push(Buffer.from(parte));
+  return Buffer.concat(partes).toString("utf8");
+}
+function preguntar(pregunta, oculto = false) {
+  const { stdin, stderr } = process;
+  return new Promise((resolve2, reject) => {
+    let texto2 = "";
+    stderr.write(pregunta);
+    if (oculto) stdin.setRawMode(true);
+    stdin.setEncoding("utf8");
+    stdin.resume();
+    const terminar = (accion) => {
+      stdin.off("data", alRecibir);
+      if (oculto) {
+        stdin.setRawMode(false);
+        stderr.write("\n");
+      }
+      stdin.pause();
+      accion();
+    };
+    const alRecibir = (dato) => {
+      for (const letra of dato) {
+        if (letra === "\n" || letra === "\r" || letra === "")
+          return terminar(() => resolve2(texto2));
+        if (letra === "")
+          return terminar(() => reject(new ErrorCli("Operaci\xF3n cancelada.", "cancelado")));
+        if (letra === "\x7F" || letra === "\b") texto2 = texto2.slice(0, -1);
+        else if (letra >= " ") texto2 += letra;
+      }
+    };
+    stdin.on("data", alRecibir);
+  });
+}
+var entorno = {
+  env: process.env,
+  fetch: (...args) => fetch(...args),
+  stdout: (linea) => void process.stdout.write(`${linea}
+`),
+  stderr: (linea) => void process.stderr.write(`${linea}
+`),
+  leerEntrada,
+  esTTY: Boolean(process.stdin.isTTY),
+  preguntar,
+  cwd: process.cwd()
+};
+process.stdout.on("error", (error) => {
+  if (error.code === "EPIPE") process.exit(0);
+});
+process.exitCode = await ejecutar(process.argv.slice(2), entorno);