SDK TypeScript/JavaScript

SDK oficial da brapi.dev para TypeScript e JavaScript, oferecendo acesso conveniente à API REST com tipos completos e suporte a async/await.

Características

✅ Tipos TypeScript completos - IntelliSense e autocomplete
✅ Suporte a Node.js e Browser - Funciona em qualquer ambiente
✅ Async/Await nativo - API moderna e fácil de usar
✅ Retry automático - Tratamento inteligente de falhas
✅ Tratamento de erros - Erros tipados e descritivos
✅ Tree-shakeable - Bundle otimizado
✅ Gerado com Stainless - Sempre atualizado com a API

Instalação

npm install brapi
# ou
yarn add brapi
# ou
pnpm add brapi
# ou
bun add brapi

Início Rápido

JavaScript

import Brapi from 'brapi';

const client = new Brapi({
  apiKey: process.env.BRAPI_API_KEY,
});

// Buscar cotação de uma ação
const quote = await client.quote.retrieve('PETR4');
console.log(quote.results[0].regularMarketPrice);

// Buscar múltiplas ações
const quotes = await client.quote.retrieve('PETR4,VALE3,ITUB4');
console.log(quotes.results);

TypeScript

import Brapi from 'brapi';

const client = new Brapi({
  apiKey: process.env.BRAPI_API_KEY,
});

// Tipos automáticos!
const quote: Brapi.QuoteRetrieveResponse = await client.quote.retrieve('PETR4');

// IntelliSense completo
const price = quote.results[0].regularMarketPrice;
const change = quote.results[0].regularMarketChangePercent;

Configuração

Variáveis de Ambiente

Crie um arquivo .env:

BRAPI_API_KEY=seu_token_aqui

Opções do Cliente

const client = new Brapi({
  apiKey: process.env.BRAPI_API_KEY, // Obrigatório
  environment: 'production', // 'production' ou 'sandbox'
  maxRetries: 2, // Número de tentativas (padrão: 2)
  timeout: 60000, // Timeout em ms (padrão: 60000)
});

Exemplos de Uso

Cotações

// Cotação única
const quote = await client.quote.retrieve('PETR4');

// Múltiplas cotações
const quotes = await client.quote.retrieve('PETR4,VALE3,ITUB4');

// Com parâmetros adicionais
const quoteWithModules = await client.quote.retrieve('PETR4', {
  modules: 'summaryProfile,balanceSheetHistory',
});

// Resultado
console.log(quote.results[0]);
// {
//   symbol: 'PETR4',
//   shortName: 'PETROBRAS PN',
//   regularMarketPrice: 38.45,
//   regularMarketChangePercent: 2.15,
//   currency: 'BRL',
//   ...
// }

Lista de Ações

// Listar todas as ações disponíveis
const stocks = await client.quote.list();

// Com paginação
const stocksPage = await client.quote.list({
  page: 1,
  limit: 50,
});

console.log(stocks.stocks);
// [
//   { stock: 'PETR4', name: 'Petrobras PN', type: 'stock' },
//   { stock: 'VALE3', name: 'Vale ON', type: 'stock' },
//   ...
// ]

Criptomoedas

// Cotação de cripto
const crypto = await client.crypto.retrieve('BTC');

// Lista de criptos disponíveis
const cryptos = await client.crypto.available();

Moedas

// Cotação de moeda
const currency = await client.currency.retrieve('USD-BRL');

// Lista de moedas disponíveis
const currencies = await client.currency.available();

Inflação

// Dados de inflação
const inflation = await client.inflation.retrieve('IPCA');

// Países disponíveis
const countries = await client.inflation.available();

Taxa de Juros

// Taxa SELIC
const selic = await client.primeRate.retrieve('SELIC');

// Países disponíveis
const countries = await client.primeRate.available();

Tratamento de Erros

A SDK lança erros tipados para facilitar o tratamento:

try {
  const quote = await client.quote.retrieve('INVALID');
} catch (error) {
  if (error instanceof Brapi.APIError) {
    console.log(error.status); // Código HTTP (ex: 404)
    console.log(error.name); // Nome do erro (ex: 'NotFoundError')
    console.log(error.message); // Mensagem descritiva
    console.log(error.headers); // Headers da resposta
  }
}

Tipos de Erro

Status Code	Error Type	Descrição
400	`BadRequestError`	Requisição inválida
401	`AuthenticationError`	Token inválido
403	`PermissionDeniedError`	Sem permissão
404	`NotFoundError`	Recurso não encontrado
422	`UnprocessableEntityError`	Dados inválidos
429	`RateLimitError`	Limite de requisições
>=500	`InternalServerError`	Erro no servidor
N/A	`APIConnectionError`	Erro de conexão

Retry Automático

A SDK tenta automaticamente 2 vezes em caso de falha:

// Configurar retries
const client = new Brapi({
  apiKey: process.env.BRAPI_API_KEY,
  maxRetries: 3, // Tenta até 3 vezes
});

// Desabilitar retries
const client = new Brapi({
  apiKey: process.env.BRAPI_API_KEY,
  maxRetries: 0, // Sem retry
});

Erros automaticamente retriados:

Erros de conexão
408 Request Timeout
409 Conflict
429 Rate Limit
Erros 5xx (servidor)

Uso em Next.js

Server Component

// app/stock/[ticker]/page.tsx
import Brapi from 'brapi';

const client = new Brapi({
  apiKey: process.env.BRAPI_API_KEY,
});

export default async function StockPage({
  params,
}: {
  params: { ticker: string };
}) {
  const quote = await client.quote.retrieve(params.ticker);
  const stock = quote.results[0];
  
  return (
    <div>
      <h1>{stock.shortName}</h1>
      <p className="text-3xl">R$ {stock.regularMarketPrice.toFixed(2)}</p>
    </div>
  );
}

API Route

// app/api/quote/[ticker]/route.ts
import { NextResponse } from 'next/server';
import Brapi from 'brapi';

const client = new Brapi({
  apiKey: process.env.BRAPI_API_KEY,
});

export async function GET(
  request: Request,
  { params }: { params: { ticker: string } }
) {
  try {
    const quote = await client.quote.retrieve(params.ticker);
    return NextResponse.json(quote);
  } catch (error) {
    if (error instanceof Brapi.NotFoundError) {
      return NextResponse.json(
        { error: 'Ticker not found' },
        { status: 404 }
      );
    }
    throw error;
  }
}

Client Component com SWR

'use client';

import useSWR from 'swr';

const fetcher = (url: string) => fetch(url).then(r => r.json());

export function StockQuote({ ticker }: { ticker: string }) {
  const { data, error } = useSWR(`/api/quote/${ticker}`, fetcher);
  
  if (error) return <div>Erro ao carregar</div>;
  if (!data) return <div>Carregando...</div>;
  
  const stock = data.results[0];
  return <div>{stock.symbol}: R$ {stock.regularMarketPrice}</div>;
}

Uso com Express

import express from 'express';
import Brapi from 'brapi';

const app = express();
const client = new Brapi({
  apiKey: process.env.BRAPI_API_KEY,
});

app.get('/api/quote/:ticker', async (req, res) => {
  try {
    const quote = await client.quote.retrieve(req.params.ticker);
    res.json(quote);
  } catch (error) {
    if (error instanceof Brapi.NotFoundError) {
      res.status(404).json({ error: 'Ticker not found' });
    } else {
      res.status(500).json({ error: 'Internal server error' });
    }
  }
});

app.listen(3000);

Timeouts

// Timeout global
const client = new Brapi({
  apiKey: process.env.BRAPI_API_KEY,
  timeout: 10000, // 10 segundos
});

// Timeout por requisição
const quote = await client.quote.retrieve('PETR4', {
  timeout: 5000, // 5 segundos
});

Tipos Disponíveis

A SDK exporta todos os tipos necessários:

import type {
  QuoteRetrieveResponse,
  QuoteListResponse,
  CryptoRetrieveResponse,
  CurrencyRetrieveResponse,
  InflationRetrieveResponse,
} from 'brapi';

Boas Práticas

1. Reutilize a Instância do Cliente

// ✅ Bom - Crie uma instância e reutilize
export const brapiClient = new Brapi({
  apiKey: process.env.BRAPI_API_KEY,
});

// ❌ Ruim - Criar nova instância a cada uso
function getQuote() {
  const client = new Brapi({ apiKey: '...' }); // Não faça isso
}

2. Use Variáveis de Ambiente

// ✅ Bom
const client = new Brapi({
  apiKey: process.env.BRAPI_API_KEY,
});

// ❌ Ruim - Nunca hardcode o token
const client = new Brapi({
  apiKey: 'meu-token-secreto', // Não faça isso!
});

3. Trate Erros Adequadamente

// ✅ Bom
try {
  const quote = await client.quote.retrieve('PETR4');
} catch (error) {
  if (error instanceof Brapi.RateLimitError) {
    // Trate limite de requisições
  } else if (error instanceof Brapi.NotFoundError) {
    // Trate ticker não encontrado
  }
}

Links Úteis

Suporte

Precisa de ajuda? Entre em contato:

Contribuindo

Contribuições são bem-vindas! Veja o guia de contribuição.

Licença

MIT License - veja LICENSE para detalhes.

Índice