Finanças SDK

SDK em TypeScript para consumo da API do aplicativo de Finanças (Finanças Cesária). Desenvolvido nativamente em ESModules e fortemente tipado utilizando definições derivadas do contrato OpenAPI.

Hospedado publicamente de forma gratuita no NPM Registry (npmjs.com).

Como Instalar (Em qualquer projeto e no Cloudflare Pages)

Como o pacote é público, você não precisa configurar nenhum token, chave SSH ou arquivo .npmrc. Ele pode ser instalado diretamente em qualquer computador e vai compilar perfeitamente no Cloudflare Pages:

npm install guimerlin-financas-sdk
# ou com pnpm
pnpm add guimerlin-financas-sdk
# ou com yarn
yarn add guimerlin-financas-sdk

Como Publicar uma Nova Versão (Manualmente)

Para publicar atualizações do pacote no registro público do NPM:

1. Faça login na sua conta NPM (se não tiver uma, crie gratuitamente em npmjs.com):

   npm login

2. Compile e Publique (lembre-se de incrementar a "version" no package.json a cada nova publicação):

   cd sdk
   npm run build
   npm publish

Inicialização e Uso do SDK

Para instanciar o cliente, forneça a URL base da API e o token de autenticação do Firebase:

import { FinancasClient } from "guimerlin-financas-sdk";

const client = new FinancasClient({
  baseUrl: 'https://api.seuservico.com.br',
  token: 'SEU_FIREBASE_ID_TOKEN' // opcional na inicialização
});

Autenticação Dinâmica

Se o token expirar ou for obtido após a inicialização, você poderá atualizá-lo diretamente no cliente:

client.token = "NOVO_FIREBASE_ID_TOKEN";

Exemplos de Uso

1. Categorias (CRUD)

// Criar uma categoria
const novaCategoria = await client.categories.create({
  name: "Alimentação",
  icon: "utensils",
  color: "#FF5733",
});
console.log("Categoria Criada:", novaCategoria.id);

// Buscar uma categoria por ID
const categoria = await client.categories.get(novaCategoria.id);
console.log("Nome:", categoria.name);

// Atualizar uma categoria
const categoriaAtualizada = await client.categories.update(novaCategoria.id, {
  name: "Supermercado e Restaurante",
});

// Deletar uma categoria
await client.categories.delete(novaCategoria.id);

2. Boletos e Parcelas (Fluxo Financeiro)

// Criar um novo boleto parcelado
const boleto = await client.boletos.create({
  name: "Compra de Computador",
  amount: 3000,
  dueDate: "2026-08-10",
  categoryId: "id-da-categoria",
  storeId: "id-da-loja",
  type: "installments", // 'single' | 'installments' | 'recurring'
  installmentsCount: 3, // Requerido se o tipo for 'installments'
});

// Pagar o boleto inteiro diretamente
await client.boletos.pay(boleto.id, {
  paidAmount: 3000,
  paymentDate: "2026-07-21",
});

// Listar parcelas
const parcelas = await client.boletos.listInstallments(boleto.id);

// Pagar uma parcela específica
await client.boletos.payInstallment(boleto.id, "id-da-parcela", {
  paidAmount: 950,
  paymentDate: "2026-07-21",
});

Paginação Transparente

Método 1: Iteração Automática (Async Iterator)

const listaBoletos = await client.boletos.list({ limit: 10 });

for await (const boleto of listaBoletos) {
  console.log(`Boleto: ${boleto.name} - Valor: R$${boleto.amount}`);
}

Método 2: Paginação Manual passo a passo

let pagina = await client.boletos.list({ limit: 10 });
console.log("Itens na página:", pagina.data);

if (pagina.hasMore) {
  pagina = await pagina.next();
  console.log("Próxima página:", pagina.data);
}

Tratamento de Erros

import { FinancasClient, FinancasClientError } from "guimerlin-financas-sdk";

try {
  await client.categories.create({ name: "" });
} catch (error) {
  if (error instanceof FinancasClientError) {
    console.error(`Erro da API (${error.status}): ${error.message}`);
    if (error.issues) {
      error.issues.forEach((issue) => {
        console.error(
          `Campo: ${issue.path.join(".")}, Detalhe: ${issue.message}`,
        );
      });
    }
  }
}