@comando.one/mcp-server 0.5.0 → 0.6.0

package/README.md

@@ -51,7 +51,7 @@ Ambos expõem o **mesmo conjunto de ferramentas** (131 curadas + `lookups` + `co
 
 ## Como funciona
 
-- **131 tools curadas** (gerados a partir do OpenAPI canônico, zero drift) cobrindo as operações de maior valor — `customers_list`, `invoices_create`/`invoices_delete`, `charges_create`, `nfse_emit`, `payouts_create`, `contracts_pause`/`contracts_resume`, `service_categories_create`, `reports_aging_actions`/`reports_cashflow_forecast`, `audit_timeline`, `documents_analyze` (lê boleto/guia/NF anexada e extrai valor, vencimento e emitente), `cost_centers_create`, etc.
+- **134 tools curadas** (gerados a partir do OpenAPI canônico, zero drift) cobrindo as operações de maior valor — `customers_list`, `invoices_create`/`invoices_delete`, `charges_create`, `nfse_emit`, `payouts_create`, `contracts_pause`/`contracts_resume`, `service_categories_create`, `reports_aging_actions`/`reports_cashflow_forecast`, `audit_timeline`, `documents_analyze` (lê boleto/guia/NF anexada e extrai valor, vencimento e emitente), `cost_centers_create`, `invoices_settle_charge` (dá baixa numa parcela — registra o recebimento), etc.
 - **`comando_request`** — escape hatch genérico (`method`, `path`, `query`, `body`) que cobre 100% dos endpoints restantes.
 - **`lookups`** — catálogos read-only (centros de custo, condições/métodos de pagamento, naturezas, contas bancárias).
 - **`whoami`** — identidade, empresas acessíveis e scopes da chave.

package/dist/index.js

@@ -144,6 +144,9 @@ var MANIFEST = [
   { operationId: "createInvoice", tool: "invoices_create", write: true },
   { operationId: "cancelInvoice", tool: "invoices_cancel", write: true, destructive: true },
   { operationId: "sendInvoiceSecondCopy", tool: "invoices_send", write: true },
+  { operationId: "setInvoiceAutoSend", tool: "invoices_set_auto_send", write: true },
+  { operationId: "listInvoiceCharges", tool: "invoices_list_charges" },
+  { operationId: "settleInvoiceCharge", tool: "invoices_settle_charge", write: true },
   { operationId: "generateContractInvoices", tool: "contracts_generate_invoices", write: true },
   // ----- Cobranças -----
   { operationId: "listCharges", tool: "charges_list" },
@@ -1154,13 +1157,13 @@ var SCHEMAS = {
   },
   InvoiceCreate: {
     type: "object",
-    required: ["customer_id"],
+    required: ["customer_id", "due_date"],
     properties: {
       customer_id: { type: "string", format: "uuid" },
       title: { type: "string" },
       amount: { type: "number", description: "Ignorado se 'items' for enviado (calculado dos itens)" },
       status: { type: "string", enum: ["rascunho", "enviada", "aceita", "ativa"], default: "rascunho" },
-      due_date: { type: "string", format: "date" },
+      due_date: { type: "string", format: "date", description: "Obrigat\xF3rio. A fatura nasce com uma parcela 1/1 neste vencimento \u2014 sem parcela ningu\xE9m cobra (o dispatch seleciona por parcela). O envio autom\xE1tico nasce desligado; para ligar use PATCH /v1/invoices/{id}/auto-send." },
       items: {
         type: "array",
         items: {
@@ -1224,7 +1227,7 @@ var SCHEMAS = {
     type: "object",
     required: ["motivo", "justificativa"],
     properties: {
-      motivo: { type: "integer", enum: [1, 2, 3, 4, 9], description: "1=n\xE3o realizada, 2=duplica\xE7\xE3o, 3=erro de emiss\xE3o, 4=servi\xE7o n\xE3o prestado, 9=outros" },
+      motivo: { type: "integer", enum: [1, 2, 3, 4, 9], description: "1=erro na emiss\xE3o, 2=servi\xE7o n\xE3o prestado, 3=duplicidade de emiss\xE3o, 4=decis\xE3o judicial, 9=outros. Use o c\xF3digo pelo R\xD3TULO, n\xE3o pela ordem." },
       justificativa: { type: "string", minLength: 15, maxLength: 255 }
     }
   },
@@ -1827,7 +1830,7 @@ var OPENAPI_SPEC = {
         tags: ["Propostas"],
         summary: "Enviar proposta",
         operationId: "sendProposal",
-        description: "Marca a proposta como enviada.",
+        description: "Apenas MUDA O STATUS da proposta para 'enviada'. N\xC3O dispara e-mail \u2014 n\xE3o existe envio de proposta por e-mail no sistema (conferido: email_schedules s\xF3 tem invoice e charge). Depois de chamar, n\xE3o afirme ao usu\xE1rio que a proposta foi enviada ao cliente.",
         security: [{ ApiKeyAuth: ["proposals:send"] }],
         responses: { "200": { description: "Proposta enviada", content: { "application/json": { schema: { $ref: "#/components/schemas/Proposal" } } } }, "404": errorResponse("Proposta n\xE3o encontrada"), "409": errorResponse("Proposta cancelada"), ...COMMON_ERRORS }
       }
@@ -2038,7 +2041,8 @@ var OPENAPI_SPEC = {
         tags: ["Contratos"],
         summary: "Gerar as faturas devidas do contrato",
         operationId: "generateContractInvoices",
-        description: "Gera as faturas em aberto do contrato conforme a periodicidade dele. A regra de compet\xEAncia (e a prote\xE7\xE3o contra duplicar fatura do mesmo per\xEDodo) \xE9 da rotina de gera\xE7\xE3o, n\xE3o deste endpoint.",
+        description: "Gera fatura do contrato. Por padr\xE3o (mode=extra) cria uma fatura AVULSA fora do ciclo: n\xE3o avan\xE7a o agendamento, ent\xE3o chamar duas vezes gera DUAS faturas. Use mode=cycle para antecipar a fatura do ciclo corrente \u2014 \xE9 esse modo que avan\xE7a next_generation_date e evita duplicar a compet\xEAncia. mode=skip pula o ciclo sem gerar nada. Contrato cancelado ou suspenso \xE9 recusado.",
+        requestBody: { required: false, content: { "application/json": { schema: { type: "object", properties: { mode: { type: "string", enum: ["extra", "cycle", "skip"], default: "extra", description: "extra = avulsa (repet\xEDvel) \xB7 cycle = fatura do ciclo, avan\xE7a o agendamento \xB7 skip = s\xF3 avan\xE7a" } } } } } },
         security: [{ ApiKeyAuth: ["invoices:create"] }],
         responses: {
           "200": {
@@ -2059,6 +2063,105 @@ var OPENAPI_SPEC = {
         }
       }
     },
+    "/invoices/{id}/auto-send": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      patch: {
+        tags: ["Faturas"],
+        summary: "Programar a cobran\xE7a autom\xE1tica",
+        operationId: "setInvoiceAutoSend",
+        description: "Liga ou desliga o envio AUTOM\xC1TICO da cobran\xE7a nas parcelas em aberto da fatura. Sem isso a cobran\xE7a nunca sai sozinha: o disparo di\xE1rio s\xF3 envia com `auto_send_enabled` ligado na parcela, e a fatura criada por API nasce desligada. `days_before` = quantos dias ANTES do vencimento disparar (0 = no dia). Desligar devolve o canal para `manual`.",
+        security: [{ ApiKeyAuth: ["invoices:send"] }],
+        requestBody: { required: true, content: { "application/json": { schema: { type: "object", properties: {
+          enabled: { type: "boolean", default: true, description: "false desliga e volta o canal para manual" },
+          channel: { type: "string", enum: ["manual", "email", "whatsapp", "ambos"], default: "email", description: '"ambos" = e-mail E WhatsApp' },
+          days_before: { type: "integer", minimum: 0, maximum: 90, default: 0, description: "dias ANTES do vencimento" }
+        } } } } },
+        responses: {
+          "200": { description: "Programa\xE7\xE3o aplicada", content: { "application/json": { schema: { type: "object", properties: {
+            invoice_id: { type: "string" },
+            auto_send_enabled: { type: "boolean" },
+            send_channel: { type: "string" },
+            send_days_before: { type: "integer" },
+            parcelas_afetadas: { type: "integer" }
+          } } } } },
+          "400": errorResponse("channel ou days_before inv\xE1lidos"),
+          "404": errorResponse("Fatura n\xE3o encontrada"),
+          "409": errorResponse("Fatura sem parcela em aberto"),
+          ...COMMON_ERRORS
+        }
+      }
+    },
+    "/invoices/{id}/charges": {
+      parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
+      get: {
+        tags: ["Faturas"],
+        summary: "Listar as parcelas da fatura",
+        operationId: "listInvoiceCharges",
+        description: "As PARCELAS (invoice_charges) da fatura, com quanto j\xE1 foi pago e quanto falta em cada uma. N\xE3o confunda com `/v1/charges`, que \xE9 a cobran\xE7a do GATEWAY (Pix/boleto emitido no banco): a parcela \xE9 o que manda no vencimento e no status de pagamento da fatura. Use esta rota para descobrir o `charge_id` antes de dar baixa.",
+        security: [{ ApiKeyAuth: ["invoices:read"] }],
+        responses: { "200": { description: "Parcelas da fatura", content: { "application/json": { schema: { type: "object", properties: {
+          invoice_id: { type: "string" },
+          invoice_number: { type: "string" },
+          invoice_status: { type: "string" },
+          invoice_payment_status: { type: "string" },
+          total: { type: "integer" },
+          charges: { type: "array", items: { type: "object", properties: {
+            id: { type: "string" },
+            sequence: { type: "integer" },
+            description: { type: "string" },
+            amount: { type: "number" },
+            due_date: { type: "string", format: "date" },
+            payment_status: { type: "string", enum: ["pendente", "parcial", "pago", "vencido"] },
+            paid_amount: { type: "number", description: "soma j\xE1 baixada nesta parcela" },
+            remaining_amount: { type: "number", description: "saldo a receber" },
+            auto_send_enabled: { type: "boolean" },
+            send_channel: { type: "string" }
+          } } }
+        } } } } }, "404": errorResponse("Fatura n\xE3o encontrada"), ...COMMON_ERRORS }
+      }
+    },
+    "/invoices/{id}/charges/{charge_id}/pay": {
+      parameters: [
+        { name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } },
+        { name: "charge_id", in: "path", required: true, schema: { type: "string", format: "uuid" }, description: "id da PARCELA (veja GET /v1/invoices/{id}/charges)" }
+      ],
+      post: {
+        tags: ["Faturas"],
+        summary: "Dar baixa em uma parcela",
+        operationId: "settleInvoiceCharge",
+        description: "Registra o recebimento de uma parcela: cria o pagamento e o aloca \xE0 parcela. A parcela e a fatura passam a `pago` (ou `parcial`) pelo pr\xF3prio banco. Sem `amount`, quita o saldo restante; sem `payment_date`, usa hoje (America/Sao_Paulo). Baixa PARCIAL \xE9 permitida; acima do saldo, n\xE3o. Campo de corpo que a rota n\xE3o conhece devolve 400 em vez de ser ignorado.",
+        security: [{ ApiKeyAuth: ["invoices:settle"] }],
+        requestBody: { required: false, content: { "application/json": { schema: { type: "object", properties: {
+          amount: { type: "number", description: "Valor recebido. Omitido, quita o saldo restante da parcela." },
+          payment_date: { type: "string", format: "date", description: "Data do recebimento (YYYY-MM-DD). Padr\xE3o: hoje." },
+          receipt_method_id: { type: "string", format: "uuid", description: "Forma de RECEBIMENTO (GET /v1/payment-methods). Aceita tamb\xE9m o nome `payment_method_id`." },
+          bank_account_id: { type: "string", format: "uuid", description: "Conta que recebeu (GET /v1/bank-accounts)." },
+          notes: { type: "string", description: "Observa\xE7\xE3o livre do pagamento." }
+        } } } } },
+        responses: {
+          "201": { description: "Baixa registrada", content: { "application/json": { schema: { type: "object", properties: {
+            payment_id: { type: "string" },
+            invoice_id: { type: "string" },
+            invoice_number: { type: "string" },
+            invoice_payment_status: { type: "string" },
+            amount: { type: "number" },
+            payment_date: { type: "string", format: "date" },
+            charge: { type: "object", properties: {
+              id: { type: "string" },
+              sequence: { type: "integer" },
+              amount: { type: "number" },
+              paid_amount: { type: "number" },
+              remaining_amount: { type: "number" },
+              payment_status: { type: "string" }
+            } }
+          } } } } },
+          "400": errorResponse("amount, payment_date ou campo de corpo inv\xE1lido"),
+          "404": errorResponse("Fatura ou parcela n\xE3o encontrada"),
+          "409": errorResponse("Fatura cancelada, parcela j\xE1 quitada ou valor acima do saldo"),
+          ...COMMON_ERRORS
+        }
+      }
+    },
     "/invoices/{id}/send": {
       parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
       post: {
@@ -2510,6 +2613,7 @@ var OPENAPI_SPEC = {
           { name: "include_shared", in: "query", schema: { type: "boolean", default: true }, description: "Incluir clientes compartilhados" },
           { name: "customer_id", in: "query", schema: { type: "string", format: "uuid" } },
           { name: "search", in: "query", schema: { type: "string" } },
+          { name: "company_id", in: "query", schema: { type: "string", format: "uuid" }, description: "Restringe a UMA empresa: a sua, ou a dona de um cliente compartilhado. Aplicado SOBRE o escopo permitido \u2014 nunca amplia acesso." },
           { name: "query", in: "query", schema: { type: "string" }, description: "Apelido de 'search' \u2014 o c\xF3digo j\xE1 aceitava os dois nomes; agora est\xE1 documentado." }
         ],
         responses: { "200": { description: "Faturas em atraso + a\xE7\xF5es recomendadas", content: { "application/json": { schema: { type: "object", properties: {
@@ -2520,6 +2624,8 @@ var OPENAPI_SPEC = {
           total_invoiced_amount: { type: "number", description: "Soma do valor cheio das mesmas faturas, ignorando pagamentos parciais." },
           actions: { type: "array", items: { type: "object", properties: {
             invoice_id: { type: "string", format: "uuid" },
+            company_id: { type: "string", format: "uuid", description: "Empresa DONA da fatura. Com clientes compartilhados a lista mistura empresas; sem este campo n\xE3o d\xE1 para saber de quem \xE9 cada linha." },
+            company_name: { type: "string", nullable: true },
             invoice_number: { type: "string", nullable: true },
             title: { type: "string", nullable: true },
             customer_id: { type: "string", format: "uuid" },
@@ -2541,6 +2647,7 @@ var OPENAPI_SPEC = {
         tags: ["Relat\xF3rios"],
         summary: "Previs\xE3o de fluxo de caixa",
         operationId: "reportCashflowForecast",
+        description: "Projeta o caixa dia a dia pelas parcelas em aberto. `total_inflow`/`total_outflow` e a `timeline` usam o **saldo devedor** de cada parcela (valor menos o que j\xE1 foi baixado) \u2014 \xE9 o que de fato entra e sai; `total_inflow_full`/`total_outflow_full` trazem o valor cheio. Parcela de fatura/compra **cancelada ou em rascunho** n\xE3o entra: o t\xEDtulo foi desfeito ou ainda n\xE3o foi emitido.",
         security: [{ ApiKeyAuth: ["finance:read"] }],
         parameters: [
           { name: "horizon_days", in: "query", schema: { type: "integer", minimum: 1, maximum: 120, default: 30 } },
@@ -2548,7 +2655,7 @@ var OPENAPI_SPEC = {
           { name: "include_receivables", in: "query", schema: { type: "boolean", default: true } },
           { name: "include_payables", in: "query", schema: { type: "boolean", default: true } }
         ],
-        responses: { "200": { description: "Proje\xE7\xE3o di\xE1ria de caixa (timeline)", content: { "application/json": { schema: { type: "object" } } } }, ...COMMON_ERRORS }
+        responses: { "200": { description: "Proje\xE7\xE3o di\xE1ria de caixa (timeline). Cada linha de `receivables_preview`/`payables_preview` traz `amount` (cheio), `paid_amount` e `outstanding_amount` (o que falta).", content: { "application/json": { schema: { type: "object" } } } }, ...COMMON_ERRORS }
       }
     },
     // -----------------------------------------------------------------------
@@ -2574,7 +2681,7 @@ var OPENAPI_SPEC = {
         tags: ["NFS-e"],
         summary: "Emitir NFS-e",
         operationId: "emitNfse",
-        description: "Emite uma NFS-e a partir de uma fatura. O m\xE9todo (certificado/portal) vem da configura\xE7\xE3o da empresa. Pode levar alguns segundos.",
+        description: "Emite uma NFS-e a partir de uma fatura. O m\xE9todo (certificado/portal) vem da configura\xE7\xE3o da empresa. Pode levar alguns segundos. **201** = autorizada ou em transmiss\xE3o; **422** = o fisco REJEITOU (o motivo vem em `message`) \u2014 nesse caso n\xE3o existe nota, n\xE3o afirme ao usu\xE1rio que foi emitida.",
         security: [{ ApiKeyAuth: ["nfse:emitir"] }],
         requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/NfseEmit" } } } },
         responses: { "201": { description: "Emiss\xE3o solicitada", content: { "application/json": { schema: { type: "object", properties: { invoice_id: { type: "string" }, status: { type: "string" }, numero_nfse: { type: ["string", "null"] }, chave_acesso: { type: ["string", "null"] }, history_id: { type: ["string", "null"] } } } } } }, "400": errorResponse("invoice_id ausente"), "404": errorResponse("Fatura n\xE3o encontrada"), "422": errorResponse("NFS-e n\xE3o configurada"), "502": errorResponse("Erro do provedor de NFS-e"), ...COMMON_ERRORS }
@@ -2621,7 +2728,7 @@ var OPENAPI_SPEC = {
         tags: ["NFS-e"],
         summary: "URLs assinadas do XML e DANFSE",
         operationId: "getNfseFiles",
-        description: "Retorna URLs tempor\xE1rias (30 min) para download do XML e do PDF (DANFSE). Gera o PDF sob demanda se a nota estiver autorizada/cancelada.",
+        description: "Retorna URLs tempor\xE1rias (30 min). `xml_signed_url` = XML autorizado. `danfse_signed_url` = DANFSe em PDF (gerada sob demanda a partir do XML se ainda n\xE3o existir). `danfse_html_signed_url` = HTML OFICIAL publicado pelo ADN, quando dispon\xEDvel \u2014 \xE9 outro documento, n\xE3o uma vers\xE3o pior do PDF. `danfse_formato` diz o que veio em `danfse_signed_url` (pdf|html).",
         security: [{ ApiKeyAuth: ["nfse:read"] }],
         responses: { "200": { description: "URLs assinadas", content: { "application/json": { schema: { type: "object", properties: { id: { type: "string" }, invoice_id: { type: "string" }, status: { type: "string" }, xml_signed_url: { type: ["string", "null"] }, danfse_signed_url: { type: ["string", "null"] }, signed_url_ttl_seconds: { type: "integer" } } } } } }, "404": errorResponse("NFS-e n\xE3o encontrada"), ...COMMON_ERRORS }
       }
@@ -3365,6 +3472,7 @@ var API_MODULES = [
       { key: "create", label: "Criar cobran\xE7a", description: "Gerar boletos, Pix e cobran\xE7as" },
       { key: "cancel", label: "Cancelar cobran\xE7a", description: "Cancelar cobran\xE7as em aberto" },
       { key: "send", label: "Enviar ao cliente", description: "Enviar segunda via da fatura por e-mail ao cliente" },
+      { key: "settle", label: "Dar baixa", description: "Registrar o recebimento de uma parcela (baixa total ou parcial)" },
       { key: "delete", label: "Excluir fatura", description: "Excluir faturas permanentemente (itens e cobran\xE7as vinculadas)" }
     ]
   },
@@ -3759,6 +3867,27 @@ function buildCuratedTools(api, heldScopes) {
 
 // src/tools/request.ts
 var METHODS = ["GET", "POST", "PATCH", "PUT", "DELETE"];
+var ROTAS_DESTRUTIVAS = (() => {
+  const out = [];
+  for (const entry of MANIFEST) {
+    if (!entry.destructive) continue;
+    let desc;
+    try {
+      desc = describeOperation(entry.operationId);
+    } catch {
+      continue;
+    }
+    const padrao = desc.pathTemplate.split("/").map(
+      (seg) => seg.startsWith("{") && seg.endsWith("}") ? "[^/]+" : seg.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+    ).join("/");
+    out.push({ method: desc.method.toUpperCase(), re: new RegExp(`^${padrao}/?$`) });
+  }
+  return out;
+})();
+function ehRotaDestrutiva(method, path) {
+  const semQuery = path.split("?")[0];
+  return ROTAS_DESTRUTIVAS.some((r) => r.method === method.toUpperCase() && r.re.test(semQuery));
+}
 function buildRequestTool(api) {
   return {
     name: "comando_request",
@@ -3782,7 +3911,7 @@ function buildRequestTool(api) {
         company_id: { type: "string", description: "Opcional: UUID da empresa (header X-Company-Id)." },
         idempotency_key: { type: "string", description: "Opcional: chave de idempot\xEAncia (POST)." },
         dry_run: { type: "boolean", description: "Se true, n\xE3o executa \u2014 s\xF3 mostra o que seria enviado." },
-        confirm: { type: "boolean", description: "Obrigat\xF3rio para DELETE: confirma a exclus\xE3o." }
+        confirm: { type: "boolean", description: "Obrigat\xF3rio para DELETE e para qualquer rota destrutiva (cancelar, estornar, pagar, reverter)." }
       }
     },
     handler: async (args) => {
@@ -3791,13 +3920,13 @@ function buildRequestTool(api) {
         if (!METHODS.includes(method)) {
           return fail(`M\xE9todo inv\xE1lido: ${args.method}. Use um de: ${METHODS.join(", ")}.`);
         }
-        if (method === "DELETE" && args.confirm !== true && args.dry_run !== true) {
+        let path = String(args.path ?? "");
+        if (!path.startsWith("/")) return fail("path deve come\xE7ar com / (ex.: /customers).");
+        if ((method === "DELETE" || ehRotaDestrutiva(method, path)) && args.confirm !== true && args.dry_run !== true) {
           return fail(
             "A\xE7\xE3o destrutiva bloqueada. Passe confirm: true para executar, ou dry_run: true para pr\xE9-visualizar."
           );
         }
-        let path = String(args.path ?? "");
-        if (!path.startsWith("/")) return fail("path deve come\xE7ar com / (ex.: /customers).");
         const queryArg = coerceObjectArg(args.query);
         if (queryArg) {
           const u = new URLSearchParams();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comando.one/mcp-server",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Servidor MCP (Model Context Protocol) para a API pública do Comando.One — opere seu ERP por linguagem natural.",
   "type": "module",
   "license": "MIT",