dualisia-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dualisia Tecnologia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# 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).

package/bin/dualisia.mjs

@@ -0,0 +1,155 @@
+#!/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;
+  }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "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"
+  }
+}

package/src/index.mjs

@@ -0,0 +1,285 @@
+/**
+ * Núcleo do CLI do Dualisia.
+ *
+ * Sem dependências e sem etapa de build: o pacote publica exatamente estes
+ * arquivos. Para um wrapper de quatro endpoints, um pipeline de bundle
+ * custaria mais manutenção do que entrega.
+ *
+ * A separação entre este módulo e `bin/dualisia.mjs` é o que torna o CLI
+ * testável: aqui só há funções puras e chamadas de `fetch`; process.argv,
+ * stdout e process.exit ficam no binário.
+ */
+
+export const DEFAULT_BASE_URL = "https://dualisia.com.br";
+
+export const USAGE = `dualisia — CLI da API do Dualisia (apuração CBS/IBS)
+
+USO
+  dualisia apurar <arquivo.xml> [--ano 2027]
+  dualisia simular <arquivo.xml> [--anos 2026,2029,2033]
+  dualisia clientes [--limit 50] [--offset 0]
+  dualisia documentos [--client-id UUID] [--from YYYY-MM-DD] [--to YYYY-MM-DD]
+
+COMANDOS
+  apurar       Apura CBS e IBS de uma NF-e. Não exige API key.
+  simular      Projeta a carga ano a ano de 2026 a 2033. Não exige API key.
+  clientes     Lista os clientes PJ do escritório. Exige API key.
+  documentos   Lista as NF-e já processadas. Exige API key.
+
+OPÇÕES GLOBAIS
+  --api-key <chave>  API key (ou variável de ambiente DUALISIA_API_KEY).
+  --base-url <url>   Origem da API (padrão: ${DEFAULT_BASE_URL}).
+  --json             Imprime a resposta bruta, sem formatação.
+  -h, --help         Mostra esta ajuda.
+  -v, --version      Mostra a versão do CLI.
+
+EXEMPLOS
+  dualisia apurar nota.xml --ano 2027
+  DUALISIA_API_KEY=dlai_live_xxx dualisia clientes --limit 10
+
+Documentação: ${DEFAULT_BASE_URL}/developers
+`;
+
+/** Comandos aceitos e se exigem API key. */
+export const COMMANDS = {
+  apurar: { needsKey: false },
+  simular: { needsKey: false },
+  clientes: { needsKey: true },
+  documentos: { needsKey: true },
+};
+
+export class CliError extends Error {
+  constructor(message, { hint = null, exitCode = 1 } = {}) {
+    super(message);
+    this.name = "CliError";
+    this.hint = hint;
+    this.exitCode = exitCode;
+  }
+}
+
+/**
+ * Faz o parse de `argv` (sem `node` nem o caminho do script).
+ *
+ * Flags no formato `--nome valor` e `--nome` booleana. Um `--` encerra o
+ * parse de flags, e tudo depois vira posicional.
+ */
+export function parseArgs(argv) {
+  const flags = {};
+  const positionals = [];
+  let onlyPositionals = false;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+
+    if (onlyPositionals || !token.startsWith("-")) {
+      positionals.push(token);
+      continue;
+    }
+
+    if (token === "--") {
+      onlyPositionals = true;
+      continue;
+    }
+
+    if (token === "-h") {
+      flags.help = true;
+      continue;
+    }
+    if (token === "-v") {
+      flags.version = true;
+      continue;
+    }
+
+    const name = token.replace(/^--/, "");
+    const next = argv[i + 1];
+
+    // Booleana quando não há próximo token ou o próximo é outra flag.
+    if (next === undefined || next.startsWith("--")) {
+      flags[name] = true;
+      continue;
+    }
+
+    flags[name] = next;
+    i += 1;
+  }
+
+  return { command: positionals[0] ?? null, positionals: positionals.slice(1), flags };
+}
+
+/** Normaliza a base URL removendo a barra final. */
+export function normalizeBaseUrl(url) {
+  const value = (url ?? DEFAULT_BASE_URL).trim();
+  return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+
+/** Monta a URL de um endpoint com query string, omitindo valores vazios. */
+export function buildUrl(baseUrl, path, query = {}) {
+  const url = new URL(path, normalizeBaseUrl(baseUrl) + "/");
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null || value === "") continue;
+    url.searchParams.set(key, String(value));
+  }
+  return url.toString();
+}
+
+/**
+ * Transforma a resposta de erro da API na mensagem que o usuário vê.
+ *
+ * A API devolve `code`, `message` e `hint`; quando algum falta (proxy no
+ * caminho, resposta não-JSON), cai num texto genérico em vez de quebrar.
+ */
+export function formatApiError(status, body) {
+  const message =
+    (body && (body.message || body.error)) || `Erro HTTP ${status}`;
+  const code = body && body.code ? ` [${body.code}]` : "";
+  const hint = body && body.hint ? `\n  → ${body.hint}` : "";
+  return `${message}${code}${hint}`;
+}
+
+/** Lê a resposta como JSON, tolerando corpo vazio ou não-JSON. */
+async function readJson(response) {
+  const text = await response.text();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+/** Executa a chamada e devolve o JSON, ou lança `CliError` formatado. */
+async function request(url, init, fetchImpl) {
+  const doFetch = fetchImpl ?? globalThis.fetch;
+  const response = await doFetch(url, init);
+  const body = await readJson(response);
+
+  if (!response.ok) {
+    throw new CliError(formatApiError(response.status, body), {
+      hint: body?.docs ? `Documentação: ${body.docs}` : null,
+      exitCode: response.status >= 500 ? 2 : 1,
+    });
+  }
+
+  return body;
+}
+
+/** Cabeçalho de autorização, ou `{}` quando o comando é público. */
+export function authHeaders(apiKey) {
+  return apiKey ? { authorization: `Bearer ${apiKey}` } : {};
+}
+
+/** `POST /api/calculadora` — apura CBS e IBS de uma NF-e. */
+export async function apurar({ baseUrl, file, filename, ano, fetchImpl }) {
+  const form = new FormData();
+  form.set("xml", file, filename);
+  if (ano) form.set("ano", String(ano));
+
+  return request(
+    buildUrl(baseUrl, "api/calculadora"),
+    { method: "POST", body: form },
+    fetchImpl,
+  );
+}
+
+/** `POST /api/simulador` — projeta a carga ano a ano. */
+export async function simular({ baseUrl, file, filename, anos, fetchImpl }) {
+  const form = new FormData();
+  form.set("xml", file, filename);
+  if (anos) form.set("anos", String(anos));
+
+  return request(
+    buildUrl(baseUrl, "api/simulador"),
+    { method: "POST", body: form },
+    fetchImpl,
+  );
+}
+
+/** `GET /api/v1/clients` — lista os clientes do escritório. */
+export async function listarClientes({
+  baseUrl,
+  apiKey,
+  limit,
+  offset,
+  fetchImpl,
+}) {
+  return request(
+    buildUrl(baseUrl, "api/v1/clients", { limit, offset }),
+    { headers: authHeaders(apiKey) },
+    fetchImpl,
+  );
+}
+
+/** `GET /api/v1/documents` — lista as NF-e processadas. */
+export async function listarDocumentos({
+  baseUrl,
+  apiKey,
+  clientId,
+  from,
+  to,
+  limit,
+  offset,
+  fetchImpl,
+}) {
+  return request(
+    buildUrl(baseUrl, "api/v1/documents", {
+      client_id: clientId,
+      from,
+      to,
+      limit,
+      offset,
+    }),
+    { headers: authHeaders(apiKey) },
+    fetchImpl,
+  );
+}
+
+/** Resumo legível de uma apuração, para quem não pediu `--json`. */
+export function formatApuracao(payload) {
+  const { nfe, resultado, anoReferencia, aliquotasEstimadas } = payload ?? {};
+  if (!nfe || !resultado) return JSON.stringify(payload, null, 2);
+
+  const money = (value) =>
+    Number(value).toLocaleString("pt-BR", {
+      style: "currency",
+      currency: "BRL",
+    });
+
+  const linhas = [
+    `Nota ${nfe.chaveAcesso}`,
+    `  Emitente        ${nfe.emitente} (${nfe.uf})`,
+    `  Valor total     ${money(nfe.valorTotal)}`,
+    `  Itens           ${nfe.itensCount}`,
+    "",
+    `Ano de referência ${anoReferencia} · modo ${resultado.modo}`,
+    `  Regime atual    ${money(resultado.regimeAtual)} (${resultado.cargaAtualPercentual}%)`,
+    `  Regime novo     ${money(resultado.regimeNovo)} (${resultado.cargaNovaPercentual}%)`,
+  ];
+
+  if (aliquotasEstimadas) {
+    linhas.push(
+      "",
+      "Atenção: este ano usa alíquotas ESTIMADAS — dependem de Resolução do Senado ainda não publicada.",
+    );
+  }
+
+  return linhas.join("\n");
+}
+
+/** Resumo legível de uma listagem paginada. */
+export function formatLista(payload, colunas) {
+  const { data, pagination } = payload ?? {};
+  if (!Array.isArray(data)) return JSON.stringify(payload, null, 2);
+
+  if (data.length === 0) return "Nenhum registro encontrado.";
+
+  const linhas = data.map((row) =>
+    colunas.map((col) => String(row[col] ?? "—")).join("  "),
+  );
+
+  linhas.push(
+    "",
+    `${data.length} de ${pagination?.total ?? "?"} registro(s) · offset ${pagination?.offset ?? 0}`,
+  );
+
+  return linhas.join("\n");
+}