dualisia-cli 0.1.0 → 0.1.2

package/README.md

@@ -1,74 +1,136 @@
-# dualisia-cli
-
-CLI oficial do [Dualisia](https://dualisia.com.br): apura CBS e IBS a partir de
-XMLs de NF-e e consulta os dados do escritório pela API REST.
-
-> **Status**: o pacote está pronto e testado, mas **ainda não foi publicado** em
-> registro público. Publicar exige credencial de npm — ver
-> "Publicação" abaixo.
-
-## Instalação
-
-Enquanto não há publicação, use direto do repositório:
-
-```bash
-node ./packages/cli/bin/dualisia.mjs --help
-```
-
-Depois de publicado:
-
-```bash
-npm install -g dualisia-cli
-```
-
-## Uso
-
-```bash
-# Apura CBS e IBS de uma nota (público, sem chave)
-dualisia apurar nota.xml --ano 2027
-
-# Projeta a carga ano a ano
-dualisia simular nota.xml --anos 2026,2029,2033
-
-# Dados do escritório (exige API key)
-export DUALISIA_API_KEY=dlai_live_xxx
-dualisia clientes --limit 10
-dualisia documentos --from 2026-01-01 --to 2026-12-31
-```
-
-`--json` imprime a resposta bruta da API, útil para encadear com `jq`.
-
-## Variáveis de ambiente
-
-| Variável | Para que serve |
-| --- | --- |
-| `DUALISIA_API_KEY` | API key da organização (`dlai_live_...`). |
-| `DUALISIA_BASE_URL` | Origem da API. Padrão: `https://dualisia.com.br`. |
-
-## Códigos de saída
-
-| Código | Significado |
-| --- | --- |
-| `0` | Sucesso. |
-| `1` | Erro de uso ou erro 4xx da API. |
-| `2` | Erro 5xx da API. |
-
-## Publicação
-
-O pacote não tem etapa de build: publica os arquivos como estão.
-
-```bash
-cd packages/cli
-npm publish
-```
-
-Requer um token de npm com permissão de publicação. O pacote não tem escopo,
-então qualquer conta autenticada que seja dona do nome publica.
-
-## Documentação da API
-
-<https://dualisia.com.br/developers> · <https://dualisia.com.br/openapi.json>
-
-## Licença
-
-MIT — ver [LICENSE](./LICENSE).
+# dualisia-cli
+
+[![npm](https://img.shields.io/npm/v/dualisia-cli)](https://www.npmjs.com/package/dualisia-cli)
+[![CI](https://github.com/munhoz-iago/dualisia-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/munhoz-iago/dualisia-cli/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/dualisia-cli)](./LICENSE)
+
+CLI oficial do [Dualisia](https://dualisia.com.br): apura **CBS** e **IBS** a
+partir de XMLs de NF-e e consulta os dados do escritório pela API REST.
+
+Entre 2026 e 2033 a Reforma Tributária brasileira roda em transição: o regime
+atual continua gerando a obrigação enquanto os tributos novos (CBS e IBS,
+LC 214/2025) precisam ser apurados em paralelo. Este CLI põe essa apuração no
+terminal — para conferir uma nota, encadear num script ou deixar um agente
+chamar sem escrever integração.
+
+## Instalação
+
+```bash
+npm install -g dualisia-cli
+```
+
+Ou sem instalar nada:
+
+```bash
+npx dualisia-cli --help
+```
+
+Requer Node.js 20 ou superior.
+
+## Uso
+
+```bash
+# Apura CBS e IBS de uma nota — público, sem chave
+dualisia apurar nota.xml --ano 2027
+
+# Projeta a carga ano a ano da transição
+dualisia simular nota.xml --anos 2026,2029,2033
+
+# Dados do escritório — exige API key
+export DUALISIA_API_KEY=dlai_live_xxx
+dualisia clientes --limit 10
+dualisia documentos --from 2026-01-01 --to 2026-12-31
+```
+
+Saída de `apurar`:
+
+```
+Nota 35260612345678000190550010000001231234567890
+  Emitente        Empresa Teste Ltda (SP)
+  Valor total     R$ 2.000,00
+  Itens           2
+
+Ano de referência 2027 · modo projecao
+  Regime atual    R$ 545,00 (27.25%)
+  Regime novo     R$ 176,00 (8.8%)
+
+Atenção: este ano usa alíquotas ESTIMADAS — dependem de Resolução do Senado
+ainda não publicada.
+```
+
+`--json` devolve a resposta bruta da API, para encadear com `jq`:
+
+```bash
+dualisia apurar nota.xml --ano 2027 --json | jq '.resultado.regimeNovo'
+```
+
+## Comandos
+
+| Comando | O que faz | Autenticação |
+| --- | --- | --- |
+| `apurar <arquivo.xml>` | Apura CBS e IBS de uma NF-e (modelo 55 ou 65). | pública |
+| `simular <arquivo.xml>` | Projeta a carga ano a ano, 2026-2033. | pública |
+| `clientes` | Lista os clientes PJ do escritório. | API key |
+| `documentos` | Lista as NF-e já processadas. | API key |
+
+A chave é gerada pelo owner do escritório no painel do Dualisia, em
+Configurações → API keys.
+
+## Variáveis de ambiente
+
+| Variável | Para que serve |
+| --- | --- |
+| `DUALISIA_API_KEY` | API key da organização (`dlai_live_...`). Equivale a `--api-key`. |
+| `DUALISIA_BASE_URL` | Origem da API. Padrão: `https://dualisia.com.br`. Equivale a `--base-url`. |
+
+## Códigos de saída
+
+| Código | Significado |
+| --- | --- |
+| `0` | Sucesso. |
+| `1` | Erro de uso ou erro 4xx da API. |
+| `2` | Erro 5xx da API. |
+
+Erros da API chegam em JSON estruturado, com um campo `code` estável para
+ramificar e um `hint` dizendo o que corrigir. O CLI imprime os dois.
+
+## O que este CLI não é
+
+O cálculo acontece no servidor: este pacote é um cliente da API do Dualisia,
+não um motor fiscal offline. Ele **não** transmite obrigação acessória à Receita
+ou à SEFAZ, não baixa XML da SEFAZ e não emite parecer fiscal.
+
+As alíquotas de 2026 a 2028 são as publicadas na LC 214/2025. De 2029 em diante
+dependem de Resolução do Senado ainda não publicada, e por isso são tratadas
+como estimativas — a saída sempre diz quando é o caso.
+
+## Desenvolvimento
+
+```bash
+git clone https://github.com/munhoz-iago/dualisia-cli.git
+cd dualisia-cli
+npm install
+npm test
+node ./bin/dualisia.mjs --help
+```
+
+Não há etapa de build: os arquivos são publicados como estão.
+
+### Publicação
+
+```bash
+npm version patch
+npm publish --otp=123456
+```
+
+O npm exige segundo fator para publicar. O `.npmrc` do repositório fixa o
+registry em HTTPS, para não depender da configuração da máquina.
+
+## Documentação da API
+
+- Portal do desenvolvedor: <https://dualisia.com.br/developers>
+- Especificação OpenAPI 3.1: <https://dualisia.com.br/openapi.json>
+
+## Licença
+
+MIT — ver [LICENSE](./LICENSE).

package/bin/dualisia.mjs

@@ -1,155 +1,163 @@
-#!/usr/bin/env node
-/**
- * Binário do CLI. Só faz I/O: lê argv e variáveis de ambiente, chama o núcleo
- * em `src/index.mjs`, escreve em stdout/stderr e define o código de saída.
- *
- * Toda a lógica testável vive no núcleo — este arquivo não tem regra de
- * negócio de propósito.
- */
-import { readFile } from "node:fs/promises";
-import { basename } from "node:path";
-import { createRequire } from "node:module";
-
-import {
-  CliError,
-  COMMANDS,
-  USAGE,
-  apurar,
-  formatApuracao,
-  formatLista,
-  listarClientes,
-  listarDocumentos,
-  parseArgs,
-  simular,
-} from "../src/index.mjs";
-
-const require = createRequire(import.meta.url);
-const { version } = require("../package.json");
-
-function fail(message, hint) {
-  process.stderr.write(`erro: ${message}\n`);
-  if (hint) process.stderr.write(`${hint}\n`);
-}
-
-async function readXml(path) {
-  if (!path) {
-    throw new CliError("Informe o caminho do arquivo XML.", {
-      hint: "Exemplo: dualisia apurar nota.xml",
-    });
-  }
-  try {
-    const buffer = await readFile(path);
-    return { file: new Blob([buffer]), filename: basename(path) };
-  } catch {
-    throw new CliError(`Não foi possível ler o arquivo: ${path}`, {
-      hint: "Confira o caminho e a permissão de leitura.",
-    });
-  }
-}
-
-async function main(argv) {
-  const { command, positionals, flags } = parseArgs(argv);
-
-  if (flags.version) {
-    process.stdout.write(`${version}\n`);
-    return 0;
-  }
-
-  if (!command || flags.help) {
-    process.stdout.write(USAGE);
-    return command ? 0 : 1;
-  }
-
-  const spec = COMMANDS[command];
-  if (!spec) {
-    fail(
-      `Comando desconhecido: ${command}`,
-      "Rode `dualisia --help` para ver os comandos disponíveis.",
-    );
-    return 1;
-  }
-
-  const apiKey = flags["api-key"] ?? process.env.DUALISIA_API_KEY ?? null;
-  if (spec.needsKey && !apiKey) {
-    fail(
-      `O comando \`${command}\` exige uma API key.`,
-      "Defina DUALISIA_API_KEY ou passe --api-key. Gere a chave em /dashboard/settings/api-keys.",
-    );
-    return 1;
-  }
-
-  const baseUrl = flags["base-url"] ?? process.env.DUALISIA_BASE_URL;
-  const raw = flags.json === true;
-
-  let payload;
-
-  switch (command) {
-    case "apurar": {
-      const { file, filename } = await readXml(positionals[0]);
-      payload = await apurar({ baseUrl, file, filename, ano: flags.ano });
-      process.stdout.write(
-        (raw ? JSON.stringify(payload, null, 2) : formatApuracao(payload)) + "\n",
-      );
-      return 0;
-    }
-
-    case "simular": {
-      const { file, filename } = await readXml(positionals[0]);
-      payload = await simular({ baseUrl, file, filename, anos: flags.anos });
-      process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
-      return 0;
-    }
-
-    case "clientes": {
-      payload = await listarClientes({
-        baseUrl,
-        apiKey,
-        limit: flags.limit,
-        offset: flags.offset,
-      });
-      process.stdout.write(
-        (raw
-          ? JSON.stringify(payload, null, 2)
-          : formatLista(payload, ["cnpj", "razao_social", "uf"])) + "\n",
-      );
-      return 0;
-    }
-
-    case "documentos": {
-      payload = await listarDocumentos({
-        baseUrl,
-        apiKey,
-        clientId: flags["client-id"],
-        from: flags.from,
-        to: flags.to,
-        limit: flags.limit,
-        offset: flags.offset,
-      });
-      process.stdout.write(
-        (raw
-          ? JSON.stringify(payload, null, 2)
-          : formatLista(payload, [
-              "chave_acesso",
-              "data_emissao",
-              "valor_total",
-            ])) + "\n",
-      );
-      return 0;
-    }
-
-    default:
-      return 1;
-  }
-}
-
-try {
-  process.exitCode = await main(process.argv.slice(2));
-} catch (error) {
-  if (error instanceof CliError) {
-    fail(error.message, error.hint);
-    process.exitCode = error.exitCode;
-  } else {
-    fail(error?.message ?? String(error));
-    process.exitCode = 1;
-  }
-}
+#!/usr/bin/env node
+/**
+ * Binário do CLI. Só faz I/O: lê argv e variáveis de ambiente, chama o núcleo
+ * em `src/index.mjs`, escreve em stdout/stderr e define o código de saída.
+ *
+ * Toda a lógica testável vive no núcleo — este arquivo não tem regra de
+ * negócio de propósito.
+ */
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+import { createRequire } from "node:module";
+
+import {
+  CliError,
+  COMMANDS,
+  USAGE,
+  apurar,
+  formatApuracao,
+  formatLista,
+  listarClientes,
+  listarDocumentos,
+  parseArgs,
+  simular,
+} from "../src/index.mjs";
+
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+
+function fail(message, hint) {
+  process.stderr.write(`erro: ${message}\n`);
+  if (hint) process.stderr.write(`${hint}\n`);
+}
+
+async function readXml(path) {
+  if (!path) {
+    throw new CliError("Informe o caminho do arquivo XML.", {
+      hint: "Exemplo: dualisia apurar nota.xml",
+    });
+  }
+  try {
+    const buffer = await readFile(path);
+    return { file: new Blob([buffer]), filename: basename(path) };
+  } catch {
+    throw new CliError(`Não foi possível ler o arquivo: ${path}`, {
+      hint: "Confira o caminho e a permissão de leitura.",
+    });
+  }
+}
+
+async function main(argv) {
+  const { command, positionals, flags } = parseArgs(argv);
+
+  if (flags.version) {
+    process.stdout.write(`${version}\n`);
+    return 0;
+  }
+
+  // Ajuda pedida explicitamente é sucesso: vai pro stdout e sai 0, senão
+  // `dualisia --help && algo` quebra e o texto polui um pipe de dados.
+  if (flags.help) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  // Invocação sem comando é erro de uso: o texto vai pro stderr e o código é 1.
+  if (!command) {
+    process.stderr.write(USAGE);
+    return 1;
+  }
+
+  const spec = COMMANDS[command];
+  if (!spec) {
+    fail(
+      `Comando desconhecido: ${command}`,
+      "Rode `dualisia --help` para ver os comandos disponíveis.",
+    );
+    return 1;
+  }
+
+  const apiKey = flags["api-key"] ?? process.env.DUALISIA_API_KEY ?? null;
+  if (spec.needsKey && !apiKey) {
+    fail(
+      `O comando \`${command}\` exige uma API key.`,
+      "Defina DUALISIA_API_KEY ou passe --api-key. Gere a chave em /dashboard/settings/api-keys.",
+    );
+    return 1;
+  }
+
+  const baseUrl = flags["base-url"] ?? process.env.DUALISIA_BASE_URL;
+  const raw = flags.json === true;
+
+  let payload;
+
+  switch (command) {
+    case "apurar": {
+      const { file, filename } = await readXml(positionals[0]);
+      payload = await apurar({ baseUrl, file, filename, ano: flags.ano });
+      process.stdout.write(
+        (raw ? JSON.stringify(payload, null, 2) : formatApuracao(payload)) + "\n",
+      );
+      return 0;
+    }
+
+    case "simular": {
+      const { file, filename } = await readXml(positionals[0]);
+      payload = await simular({ baseUrl, file, filename, anos: flags.anos });
+      process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+      return 0;
+    }
+
+    case "clientes": {
+      payload = await listarClientes({
+        baseUrl,
+        apiKey,
+        limit: flags.limit,
+        offset: flags.offset,
+      });
+      process.stdout.write(
+        (raw
+          ? JSON.stringify(payload, null, 2)
+          : formatLista(payload, ["cnpj", "razao_social", "uf"])) + "\n",
+      );
+      return 0;
+    }
+
+    case "documentos": {
+      payload = await listarDocumentos({
+        baseUrl,
+        apiKey,
+        clientId: flags["client-id"],
+        from: flags.from,
+        to: flags.to,
+        limit: flags.limit,
+        offset: flags.offset,
+      });
+      process.stdout.write(
+        (raw
+          ? JSON.stringify(payload, null, 2)
+          : formatLista(payload, [
+              "chave_acesso",
+              "data_emissao",
+              "valor_total",
+            ])) + "\n",
+      );
+      return 0;
+    }
+
+    default:
+      return 1;
+  }
+}
+
+try {
+  process.exitCode = await main(process.argv.slice(2));
+} catch (error) {
+  if (error instanceof CliError) {
+    fail(error.message, error.hint);
+    process.exitCode = error.exitCode;
+  } else {
+    fail(error?.message ?? String(error));
+    process.exitCode = 1;
+  }
+}

package/package.json

@@ -1,37 +1,46 @@
-{
-  "name": "dualisia-cli",
-  "version": "0.1.0",
-  "description": "CLI oficial do Dualisia: apura CBS e IBS de XMLs de NF-e e consulta os dados do escritório pela API REST.",
-  "keywords": [
-    "cbs",
-    "ibs",
-    "reforma-tributaria",
-    "nfe",
-    "fiscal",
-    "brasil",
-    "dualisia"
-  ],
-  "homepage": "https://dualisia.com.br/developers",
-  "bugs": "https://dualisia.com.br/contato",
-  "license": "MIT",
-  "author": "Dualisia Tecnologia",
-  "type": "module",
-  "bin": {
-    "dualisia": "bin/dualisia.mjs"
-  },
-  "exports": {
-    ".": "./src/index.mjs"
-  },
-  "files": [
-    "bin",
-    "src/index.mjs",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "smoke": "node ./bin/dualisia.mjs --help"
-  }
-}
+{
+  "name": "dualisia-cli",
+  "version": "0.1.2",
+  "description": "CLI oficial do Dualisia: apura CBS e IBS de XMLs de NF-e e consulta os dados do escritório pela API REST.",
+  "keywords": [
+    "cbs",
+    "ibs",
+    "reforma-tributaria",
+    "nfe",
+    "fiscal",
+    "brasil",
+    "dualisia"
+  ],
+  "homepage": "https://dualisia.com.br/developers",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/munhoz-iago/dualisia-cli.git"
+  },
+  "bugs": "https://github.com/munhoz-iago/dualisia-cli/issues",
+  "license": "MIT",
+  "author": "Dualisia Tecnologia",
+  "type": "module",
+  "bin": {
+    "dualisia": "bin/dualisia.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "files": [
+    "bin",
+    "src/index.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "smoke": "node ./bin/dualisia.mjs --help"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.5"
+  }
+}