🧠 Fire SDK

SDK completo de autenticação e banco de dados Firebase para projetos Next.js 15 (App Router). Inclui autenticação com sessão automática, proteção de rotas, integração com Firestore e suporte a regras de negócio personalizadas no backend.

🔒 Foco em segurança (cookies HTTP-only)

⚡️ Rápida integração com Firebase Admin + Client

📦 Pronto para produção e ambiente serverless

📚 Índice

• Funcionalidades
• Instalação
• Configuração
• Uso no Frontend
• Uso no Backend
• Regras de negócio
• Estrutura injetada automaticamente
• Variáveis de ambiente
• Licença

🚀 Funcionalidades

• ✅ Autenticação via Google com Firebase (popup)
• ✅ Sessão persistente via cookie HTTP-only seguro (7 dias)
• ✅ CRUD genérico com Firestore no backend
• ✅ SDK cliente para operações seguras (sdk.db.create, sdk.db.read, etc.)
• ✅ Proteção de rotas com withAuth
• ✅ Suporte a regras de negócio customizáveis
• ✅ Tipagem compartilhada (interfaces.ts) para consistência entre client/server
• ✅ Suporte total a App Router (Next.js 15)

📦 Instalação

npm install fire-sdk
# ou
yarn add fire-sdk

Ao instalar, o SDK executa um postinstall que injeta automaticamente:

• Rotas API de sessão (/api/auth/session)
• Rota de logout (/api/auth/logout)
• Rota de CRUD genérico (/api/crud)
• Arquivo de regras (/lib/rules/index.ts)

⚙️ Configuração

🔐 Variáveis de ambiente

Adicione no .env.local:

SERVICE_KEY_JSON='{"type":"service_account","project_id":"...","private_key":"..."}'

NEXT_PUBLIC_FIREBASE_API_KEY="sua-api-key"
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN="seu-projeto.firebaseapp.com"
NEXT_PUBLIC_FIREBASE_PROJECT_ID="seu-projeto-id"
NEXT_PUBLIC_FIREBASE_APP_ID="seu-app-id"

O SERVICE_KEY_JSON deve conter a service account do Firebase Admin SDK. Recomendado: JSON compactado (sem quebras de linha).

🧠 Uso no Frontend

🔁 Inicialização

// client.ts
import { sdk } from 'fire-sdk/client';

const auth = sdk.auth;
const db = sdk.db;

🔐 Login com redirecionamento

const result = await sdk.auth.signInWithGoogle('/dashboard');

if (!result.success) {
  alert(result.error);
}

🔓 Logout

await sdk.auth.signOut('/');

📍 Sessão atual

const { session, loading } = sdk.useSession();

if (!session) return <p>Você não está autenticado</p>;

🔒 Proteção de rotas com withAuth

import { sdk } from 'fire-sdk/client';

function Dashboard() {
  return <p>Área protegida</p>;
}

export default sdk.withAuth(Dashboard);

🧾 Operações de banco de dados

// Criar documento
await sdk.db.create('transactions', {
  type: 'entrada',
  value: 100,
});

// Buscar por condição
await sdk.db.readwhere('transactions', {
  field: 'createdBy',
  operator: '==',
  value: session.uid,
});

// Atualizar
await sdk.db.update('transactions', 'docId', { value: 200 });

// Excluir
await sdk.db.delete('transactions', 'docId');

Você pode adicionar uma seção rápida dentro de "🧾 Operações de banco de dados" e também um lembrete em "Uso no Backend", destacando a importância do try/catch. Aqui está a sugestão de texto a ser inserida:

⚠️ Tratamento de Erros

Todas as operações (create, read, update, etc.) retornam promises e podem falhar. Use try/catch para capturar e tratar erros de forma adequada, especialmente em ambientes de produção:

try {
  await sdk.db.create('transactions', { type: 'entrada', value: 100 });
} catch (error) {
  console.error('Erro ao criar transação:', error);
}

Isso garante que erros como falta de permissão, problemas de rede ou falhas de validação não quebrem a aplicação.

🧰 Uso no Backend

🧱 Serviço genérico de CRUD (Firestore)

Já injetado em /api/crud:

const res = await fetch('/api/crud', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    action: 'create',
    collection: 'transactions',
    data: { ... },
  }),
});

📌 Operações suportadas

| Ação | Descrição | | ----------- | ----------------------------------------------------------- | | create | Cria um novo documento | | read | Busca um documento pelo docId | | readwhere | Retorna documentos por query (field, operator, value) | | update | Atualiza documento por docId | | delete | Remove documento por docId |

📜 Regras de negócio

Você pode definir validações específicas da sua aplicação em:

// lib/rules/index.ts
export const consumerRules: Rules = {
  transactions: {
    beforeCreate: (data, session) => {
      if (data.value < 0) throw new Error('Valor inválido');
      data.createdBy = session.uid;
      return data;
    },
  },
};

Isso é útil para validar dados ou modificar dinamicamente os payloads.

🧬 Estrutura injetada automaticamente

Ao instalar o SDK, os seguintes arquivos são criados no projeto:

├── app
│   └── api
│       ├── auth
│       │   ├── session/route.ts
│       │   └── logout/route.ts
│       └── crud/route.ts
├── lib
│   └── rules
│       └── index.ts

🧾 Tipagem compartilhada

Você pode usar as interfaces do SDK para manter consistência:

import { CRUDAction, Query } from 'fire-sdk/interfaces';

Isso evita depender de imports server no client.

🌍 Variáveis de ambiente

| Nome | Descrição | Obrigatório | | ------------------------ | -------------------------------------------------- | ----------- | | SERVICE_KEY_JSON | JSON da service account do Firebase (Admin SDK) | ✅ | | NEXT_PUBLIC_FIREBASE_* | Configurações públicas do Firebase para o frontend | ✅ |

📄 Licença

MIT © Fire Team

🧠 Criado por

• Bruno Oliveira
• Github: https://github.com/odevbruno
• Youtube: https://www.youtube.com/@odevbruno
• Linkedin: https://www.linkedin.com/in/bruno-oliveira-7294a421b