Bonfire API - Documentação Completa

API modularizada para o ecossistema Bonfire, desenvolvida com foco em escalabilidade, segurança e performance.

📋 Índice

• Visão Geral
• Tecnologias
• Instalação
• Configuração
• Arquitetura
• Autenticação
• Middlewares
• Sistema de Crons
• Tratamento de Erros
• Contribuição

🔍 Visão Geral

A Bonfire API é uma solução robusta para gerenciamento de espaços educacionais, oferecendo funcionalidades como:

• Gestão de Usuários: Sistema completo de autenticação e autorização
• Espaços Virtuais: Criação e gerenciamento de ambientes de aprendizagem
• Sistema Econômico: Moedas virtuais, transações e investimentos
• Módulos Educacionais: Classes, posts, formulários e tickets
• Sistema de Arquivos: Upload e gerenciamento de mídias

Principais Características

• ✅ Modular: Arquitetura baseada em recursos independentes
• ✅ Escalável: Preparada para crescimento horizontal
• ✅ Segura: Múltiplas camadas de autenticação e autorização
• ✅ Performática: Otimizada para alto volume de requisições
• ✅ Documentada: Código autoexplicativo e bem estruturado

🛠 Tecnologias

Core

Database & Storage

Security & Auth

Development

📦 Instalação

Pré-requisitos

• Node.js 18+
• MongoDB 6+
• AWS S3 (para storage)
• Git

Instalação Local

# Clone o repositório
git clone https://github.com/thebonfiretech/bonfire-api.git

# Navegue para o diretório
cd bonfire-api

# Instale as dependências
npm install

# Configure as variáveis de ambiente
cp .env.example .env

Scripts Disponíveis

# Desenvolvimento
npm run dev

# Produção
npm run build
npm start

# Outras ferramentas
npm run control-access  # Gerar tokens de acesso
npm run publish         # Atualizar versão

⚙️ Configuração

Variáveis de Ambiente

Copie .env.example para .env e configure:

# Database
MONGO_URI=mongodb+srv://<user>:<password>@<cluster>.mongodb.net/

# Authentication
PRIVATE_ACCESS_TOKEN=<sha-512-hash>
PUBLIC_ACCESS_TOKEN=<sha-256-hash>
SECRET=<jwt-secret>

# Storage (AWS S3)
STORAGE_SECRET=<aws-secret>
STORAGE_ID=<aws-access-key>
STORAGE_URL=<s3-endpoint>
STORAGE_BUCKET_NAME=<bucket-name>

# Application
PRODUCTION=false
PORT=1000

Configuração de Produção

Para ambiente de produção, configure:

• PRODUCTION=true
• Logs desabilitados
• Compressão ativada
• Rate limiting configurado

🏗 Arquitetura

Estrutura de Diretórios

bonfire-api/
├── dist/                    # Build de produção
├── src/
│   ├── assets/             # Configurações e conteúdo
│   │   ├── config/         # Arquivos de configuração
│   │   └── content/        # Conteúdo estático (badwords, etc.)
│   ├── crons/              # Jobs agendados
│   ├── database/           # Modelos e funções de BD
│   │   ├── functions/      # Funções auxiliares
│   │   └── model/          # Schemas Mongoose
│   ├── middlewares/        # Middlewares Express
│   ├── resources/          # Lógica de negócio
│   ├── routes/             # Definição de rotas
│   ├── utils/              # Utilitários e serviços
│   ├── app.ts             # Configuração do Express
│   └── server.ts          # Ponto de entrada
├── package.json
├── tsconfig.json
└── README.md

Padrões de Código

Clean Code

• Funções de responsabilidade única
• Nomenclatura descritiva
• Sem comentários desnecessários
• Retornos antecipados

Nomenclatura

• camelCase: variáveis, funções, arquivos
• PascalCase: tipos, classes, interfaces
• kebab-case: URLs e IDs

Tratamento de Erros

try {
  // Lógica do negócio
  if (!requiredField) {
    return manageError({ code: "invalid_data" });
  }
  
  // Processamento...
  
} catch (error) {
  manageError({ code: "internal_error", error });
}

🔐 Autenticação

Sistema de Tokens

A API utiliza um sistema duplo de autenticação:

1. Control Access Token: Valida acesso à API
2. JWT Token: Identifica usuários autenticados

Middlewares de Autenticação

controlAccess

Valida tokens de acesso à API:

headers: {
  'controlAccess': '<control-access-token>'
}

auth

Valida autenticação de usuário:

headers: {
  'authorization': '<jwt-token>'
}

hasAdmin

Verifica privilégios administrativos.

Gerar Tokens de Controle

npm run control-access

🌐 Endpoints da API

Base URLs

Produção: https://api.thebonfire.com.br/v1
Desenvolvimento: https://api-dev.thebonfire.com.br/v1

Rotas Principais

Ping & Validação

GET /ping
GET /validate/control-access

Usuários

POST /users/auth/signup
POST /users/auth/signin
GET /users/auth/me
PATCH /users/profile/update

Espaços

GET /spaces/:spaceID
GET /spaces/full/:spaceID
GET /spaces/:spaceID/metrics
GET /spaces/:spaceID/users
POST /spaces/:spaceID/users/add
POST /spaces/:spaceID/users/remove

Economia

GET /economy/transactions
POST /economy/pix/:keyID
GET /economy/:spaceID/investments
POST /economy/:spaceID/investments/create

Classes

POST /classes/create
GET /classes/:classID
GET /classes/:classID/users
POST /classes/:classID/users/add

Posts

POST /posts/create
GET /posts/:postID
PATCH /posts/:postID/update
DELETE /posts/:postID/delete

Formulários

POST /forms/control/create
GET /forms/control/:formControlID
POST /forms/:name/send

Tickets

POST /tickets/create
GET /tickets/:ticketID
GET /tickets/space/:spaceID

Arquivos

POST /files/upload/:scope/:id

Administração (Admin only)

GET /admin/users
POST /admin/users/create
GET /admin/spaces
POST /admin/spaces/create

Headers Necessários

{
  'Content-Type': 'application/json',
  'controlAccess': '<control-access-token>',
  'authorization': '<jwt-token>',      // Para rotas autenticadas
  'spaceID': '<space-id>',            // Para verificação de permissões
  'classID': '<class-id>'             // Quando aplicável
}

🔧 Middlewares

manageRequest

Middleware principal que encapsula a lógica de recursos:

const exampleResource = async ({ data, manageError, ids }: ManageRequestBody) => {
  try {
    if (!data.requiredField) {
      return manageError({ code: "invalid_data" });
    }
    
    // Lógica do negócio
    
    return result;
  } catch (error) {
    manageError({ code: "internal_error", error });
  }
};

// Uso na rota
router.post("/example", manageRequest(exampleResource));

upload

Middleware para upload de arquivos:

router.post("/upload", 
  upload.array("files", 10), 
  manageRequest(uploadResource, { upload: true })
);

⏰ Sistema de Crons

Coin Distribution

Distribui moedas automaticamente:

const coinDistribution: CronTask = {
  name: "coinDistribution",
  schedule: "0 0 * * *",  // Diário às 00:00
  enabled: true,
  task: async () => {
    // Lógica de distribuição
  }
};

❌ Tratamento de Erros

Códigos de Erro

type ResponseErrorsParams = 
  | "internal_error"           // 500
  | "invalid_credentials"      // 401
  | "access_denied"           // 401
  | "user_not_found"          // 404
  | "space_not_found"         // 404
  | "invalid_data"            // 400
  | "insufficient_coins"      // 409
  // ... mais códigos

Estrutura de Resposta

interface ResponseError {
  statusCode: number;
  message: string;
}

Uso

// No recurso
if (!requiredField) {
  return manageError({ code: "invalid_data" });
}

// Resposta HTTP
{
  "statusCode": 400,
  "message": "Dados inválidos enviados"
}

🤝 Contribuição

Padrões de Contribuição

Este documento descreve o passo a passo básico para contribuir nos projetos.

Nomeação de Branch

• feat/nome-da-feature para novas funcionalidades
• fix/descricao-do-bug para correções de bugs
• docs/topico para atualizações de documentação
• chore/descricao-da-tarefa para tarefas de manutenção

Commit

Formato: <type>: <descrição curta>

• type: feat, fix, docs, style, refactor, test, chore
• descrição curta: verbo no imperativo, sem ponto final (em inglês)

Exemplo:

feat: adiciona validação de senha

Dica de Commit Automático

Use a ferramenta commiter-cli para padronizar e traduzir commits automaticamente.

1. Instale globalmente:

npm install -g commiter-cli

2. Para criar um commit, execute:

commiter use

3. Responda aos prompts:

? Mensagem do commit:
? Tipo de commit (feat, fix, docs, style, refactor, test, chore):

Como Enviar a Branch e Abrir um Pull Request

1. Confirme que está na branch correta:

git checkout feat/nome-da-feature

2. Faça o push da branch:

git push -u origin feat/nome-da-feature

3. No GitHub, clique em Compare & pull request e, em seguida, Create pull request.

Padrões de Código

• Clean Code: código claro, simples e de fácil manutenção
• Arrow Functions: use sempre arrow functions em vez de function
• Nomenclaturas:
  • Variáveis e funções: camelCase
  • Tipos/interfaces: PascalCase
• Importação de tipos: utilize sempre import type, ex.:

import type { Usuario } from "./types";

• Espaçamento por escopo: separe blocos lógicos com linhas em branco
• Ordem de importações (com linha em branco entre cada grupo):
  1. Bibliotecas externas (ex.: express, mongoose)
  2. Arquivos internos (ex.: ./utils/logger, ../utils/helper)
  3. Tipagens gerais (ex.: import type { RootState } from "@store";)

Desenvolvimento Local

# Branch para nova feature
git checkout -b feat/nova-funcionalidade

# Desenvolvimento
npm run dev

# Teste as mudanças
# Commit e push
git add .
git commit -m "feat: adiciona nova funcionalidade"
git push origin feat/nova-funcionalidade

Publicação

# Atualiza versão, realiza o commit e o push
npm run publish

📝 Licença

ISC License - Veja o arquivo LICENSE para detalhes.

👥 Autores

• @odutradev

Documentação atualizada na versão 1.4.5