taco-api-sdk

🇺🇸 Read in English

SDK oficial em TypeScript para a TacoAPI — dados nutricionais da Tabela Brasileira de Composição de Alimentos (TBCA), servidos através do gateway do RapidAPI.

Funciona em Node.js 18+ e em browsers modernos (usa fetch nativo, zero dependências obrigatórias em runtime), com build ESM e CommonJS, totalmente tipado e sem any público.

Pré-requisito

Este SDK só funciona através do RapidAPI. Não existe mais chave direta/self-serve — toda requisição precisa estar autenticada com uma assinatura do RapidAPI. Chamadas que tentam contornar o gateway são rejeitadas com 403 gateway_required.

Instalação

npm i taco-api-sdk

Primeiros passos: assinando no RapidAPI

Antes de escrever qualquer código, você precisa de uma conta no RapidAPI e uma assinatura ativa:

1. Acesse a página da TacoAPI no RapidAPI.
2. Faça login (ou crie uma conta gratuita no RapidAPI).
3. Assine um plano — o FREE não custa nada e já é suficiente pra começar (veja a tabela de Planos abaixo).
4. Depois de assinar, abra a aba "Endpoints" e copie sua X-RapidAPI-Key no painel de snippets de código à direita (é a mesma chave usada em todas as APIs do RapidAPI que você assinar).
5. Guarde essa chave como variável de ambiente — nunca a deixe hardcoded nem a envie pro controle de versão:

# .env
RAPIDAPI_KEY=sua-chave-do-rapidapi-aqui

Quickstart

import { TacoAPI } from 'taco-api-sdk'

const taco = new TacoAPI({
  apiKey: process.env.RAPIDAPI_KEY!,
})

const { results } = await taco.foods.list({ q: 'arroz', limit: 5 })
console.log(results)

O construtor valida a chave de forma síncrona e lança erro imediatamente se ela estiver ausente, antes de qualquer chamada de rede. Ele monta automaticamente os headers X-RapidAPI-Key e X-RapidAPI-Host em toda requisição — não existe (nem existirá, por decisão de design) uma opção para usar x-api-key direto.

Planos

| Plano | Preço | Limite | | ----- | ------------ | --------------------------------------------------------- | | FREE | US$ 0,00/mês | 50 requisições/dia | | PRO | US$ 1,99/mês | 5.000 requisições/mês, inclui acesso ao endpoint de IA |

O controle de quota é feito inteiramente pelo RapidAPI, não pelo SDK. Se quiser exibir a quota restante para seus usuários, leia os headers que o RapidAPI devolve na resposta (X-RateLimit-Requests-Remaining, X-RateLimit-Requests-Limit) — este SDK não controla nem gerencia quota localmente.

Referência de métodos

foods

| Método | HTTP | Descrição | | ---------------------------------------- | ---------------------------------- | ----------------------------------------------------------- | | foods.list(params?) | GET /foods | Lista paginada com filtros | | foods.get(id) | GET /foods/:id | Detalhes completos (macros + micros) | | foods.calculate(id, { grams }) | GET /foods/:id/calculate | Recalcula macros/micros pra uma quantidade em gramas | | foods.calculateMeal(items) | POST /foods/calculate-meal | Soma nutricional de uma lista de itens | | foods.random() | GET /foods/random | Um alimento aleatório | | foods.stats() | GET /foods/stats | Contagem total de alimentos/categorias | | foods.averages() | GET /foods/averages | Médias globais de macros | | foods.searchByNutrientRange(params) | GET /foods/search/nutrients | Busca por faixa min/max de kcal, proteína, carbo, lipídeos | | foods.rankingProtein() | GET /foods/ranking/protein | Top 10 proteicos | | foods.rankingFiber() | GET /foods/ranking/fiber | Top 10 fibras | | foods.rankingLowCalorie() | GET /foods/ranking/low-calorie | Top 10 menor caloria | | foods.categories() | GET /foods/categories | Lista categorias | | foods.byCategory(categoryId) | GET /foods/categories/:id/foods | Alimentos de uma categoria |

ai (requer plano PRO ou superior)

| Método | HTTP | Descrição | | --------------------- | ------------------- | ------------------------------------------------------------ | | ai.suggest(prompt) | POST /ai/suggest | Nutricionista IA — linguagem natural → alimentos sugeridos |

const suggestion = await taco.ai.suggest('quero algo rico em proteína e pobre em carboidrato')
console.log(suggestion.ai_message, suggestion.results)

O endpoint /ai/suggest retorna 403 para assinantes do plano FREE. O SDK propaga isso como um TacoForbiddenError tipado, em vez de mascarar ou reformatar a mensagem do servidor.

A documentação completa dos tipos de retorno está em src/types.ts e é navegável via TSDoc direto no seu editor.

Tratamento de erros

Toda chamada rejeita com uma subclasse tipada de TacoApiError — nunca com o corpo cru da resposta:

import { TacoAPI, TacoForbiddenError, TacoNotFoundError, TacoQuotaExceededError } from 'taco-api-sdk'

try {
  await taco.foods.get(999999)
} catch (err) {
  if (err instanceof TacoNotFoundError) {
    console.log('Alimento não encontrado')
  } else if (err instanceof TacoForbiddenError) {
    console.log('Fora do gateway RapidAPI, ou plano sem acesso ao recurso:', err.message)
  } else if (err instanceof TacoQuotaExceededError) {
    console.log('Rate limit geral por IP atingido, tente novamente em instantes')
  } else {
    throw err
  }
}

| Classe | Status HTTP | Quando ocorre | | -------------------------- | ----------- | --------------------------------------------------------------------- | | TacoAuthError | 401 | Chave RapidAPI inválida ou ausente | | TacoForbiddenError | 403 | Chamada fora do gateway RapidAPI, ou endpoint de IA fora do plano | | TacoQuotaExceededError | 429 | Rate limiter geral por IP (não é controle de quota por plano) | | TacoNotFoundError | 404 | Recurso não encontrado | | TacoServerError | >=500 | Erro no servidor da TacoAPI | | TacoApiError | outros | Classe base — qualquer outro status não coberto acima |

Todas as subclasses expõem status (número HTTP) e body (payload cru retornado pela API).

Comportamento de rede

• Retries: 1-2 tentativas automáticas com backoff exponencial curto, apenas para erros de rede/timeout e 5xx. Nunca há retry automático em 401/403/404/429.
• Timeout: 10s por request por padrão, configurável via new TacoAPI({ timeoutMs }).
• Zero dependências obrigatórias em runtime.

Exemplos

Veja examples/node.ts para um passo a passo completo em Node.js e examples/browser.html para um exemplo mínimo de uso no browser.

Links

• Documentação (Swagger): https://taco.codivatech.com/developer/docs
• Marketplace RapidAPI: https://rapidapi.com/Dants0/api/taco-api-br1

Licença

MIT — veja LICENSE.