quantictech-subscription-components/PUBLISH.md

Biblioteca de componentes reutilizáveis para sistema de assinatura com Stripe - Arquitetura Service-to-Service

# 📦 Guia de Publicação e Integração

Este guia mostra como publicar a biblioteca no NPM e integrar em outros projetos.

## 🚀 Passo 1: Preparar para Publicação

### 1.1 Build da Biblioteca

Na pasta `subscription-components`:

```bash
cd subscription-components
npm install
npm run build
```

### 1.2 Testar Localmente

Antes de publicar, teste a biblioteca localmente:

```bash
# Na pasta da biblioteca
npm pack

# Isso criará um arquivo .tgz
# Copie para outro projeto para testar:
# npm install ./quantictech-subscription-components-1.0.0.tgz
```

### 1.3 Verificar Estrutura

Certifique-se de que a estrutura está correta:

```
subscription-components/
├── dist/                   # Arquivos compilados
├── templates/              # Templates de API
├── src/                    # Código fonte
├── package.json
├── tsconfig.json
└── README.md
```

## 📤 Passo 2: Publicar no NPM

### 2.1 Login no NPM

```bash
npm login
```

### 2.2 Publicar

```bash
npm publish --access public
```

### 2.3 Verificar Publicação

Acesse: https://www.npmjs.com/package/quantictech-subscription-components

## 🔧 Passo 3: Integrar em Outros Projetos

### 3.1 Instalar no Projeto Destino

```bash
cd meu-outro-projeto
npm install quantictech-subscription-components
```

### 3.2 Instalar Dependências Necessárias

```bash
npm install @mui/material @mui/icons-material @stripe/react-stripe-js @stripe/stripe-js stripe axios micro micro-cors
```

### 3.3 Configurar Variáveis de Ambiente

Crie `.env.local`:

```env
STRIPE_SECRET_KEY=sk_test_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
```

### 3.4 Copiar Templates de API

```bash
# Criar pasta se não existir
mkdir -p pages/api

# Copiar templates
cp -r node_modules/quantictech-subscription-components/templates/webhook-api/* pages/api/
```

### 3.5 Usar Componentes

```tsx
// pages/dashboard.tsx
import { SubscriptionSummary } from 'quantictech-subscription-components';

export default function Dashboard() {
  return (
    <div>
      <h1>Dashboard</h1>
      <SubscriptionSummary showDetailedHistory={true} />
    </div>
  );
}
```

```tsx
// pages/assinatura.tsx
import { SubscriptionButton } from 'quantictech-subscription-components';

export default function Assinatura() {
  return (
    <div>
      <h1>Escolha seu Plano</h1>
      <SubscriptionButton planId="price_1234567890" />
    </div>
  );
}
```

## 🔄 Passo 4: Atualização da Biblioteca

### 4.1 Quando Fazer Updates

Para atualizar a biblioteca, altere a versão no `package.json`:

```json
{
  "version": "1.0.1"
}
```

### 4.2 Republicar

```bash
npm run build
npm publish
```

### 4.3 Atualizar nos Projetos

```bash
npm update quantictech-subscription-components
```

## 📋 Passo 5: Checklist de Integração

Para cada novo projeto que usar a biblioteca:

- [ ] ✅ Instalar biblioteca e dependências
- [ ] ✅ Configurar variáveis de ambiente do Stripe
- [ ] ✅ Copiar templates de API
- [ ] ✅ Customizar lógica de negócio nos templates
- [ ] ✅ Configurar webhook no Stripe dashboard
- [ ] ✅ Testar fluxo completo de assinatura
- [ ] ✅ Testar cancelamento e reativação

## 🎯 Passo 6: Customização por Projeto

Cada projeto pode customizar os templates copiados:

### 6.1 Webhook Principal

Em `pages/api/webhook.ts`, customize as funções:

```typescript
async function handleSubscriptionCreated(subscription: Stripe.Subscription) {
  console.log('✅ Assinatura criada:', subscription.id);
  
  // 🎯 CUSTOMIZAR AQUI:
  // - Salvar no banco de dados específico do projeto
  // - Enviar email de boas-vindas
  // - Ativar recursos premium
  // - Integrar com outros sistemas
}
```

### 6.2 Lógica de Cancelamento

Em `pages/api/cancel-subscription.ts`:

```typescript
// TODO: Adicionar lógica específica do projeto (salvar no banco, enviar email, etc.)
// 🎯 CUSTOMIZAR:
// - Atualizar status no banco
// - Enviar email de cancelamento
// - Revogar acessos específicos
```

### 6.3 APIs Personalizadas

Você pode criar APIs adicionais específicas para cada projeto:

```typescript
// pages/api/user-subscription.ts
export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  // Buscar assinatura do usuário no banco específico do projeto
  // Retornar no formato esperado pela biblioteca
}
```

## 🔒 Passo 7: Configuração de Segurança

### 7.1 Webhook no Stripe

1. Dashboard Stripe → Webhooks → Add endpoint
2. URL: `https://seudominio.com/api/webhook`
3. Eventos:
   - `customer.subscription.created`
   - `customer.subscription.updated`
   - `customer.subscription.deleted`
   - `invoice.payment_succeeded`
   - `invoice.payment_failed`

### 7.2 Variáveis de Ambiente por Ambiente

```bash
# Desenvolvimento
STRIPE_SECRET_KEY=sk_test_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...

# Produção
STRIPE_SECRET_KEY=sk_live_...
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...
```

## 📊 Passo 8: Monitoramento

### 8.1 Logs do Stripe

Monitore os logs no dashboard do Stripe:
- Webhooks → View logs
- Payments → View details

### 8.2 Logs da Aplicação

Os templates incluem logs detalhados:

```javascript
console.log('🔔 Webhook recebido:', event.type);
console.log('✅ Assinatura criada:', subscription.id);
console.log('❌ Erro ao processar:', error);
```

## 🚨 Troubleshooting

### Problemas Comuns:

#### 1. Webhook não está funcionando
```bash
# Testar localmente com Stripe CLI
stripe listen --forward-to localhost:3000/api/webhook
```

#### 2. Componentes não carregam
```bash
# Verificar se peer dependencies estão instaladas
npm ls @mui/material @stripe/react-stripe-js
```

#### 3. Erro de autenticação Stripe
```bash
# Verificar se variáveis de ambiente estão corretas
echo $STRIPE_SECRET_KEY
```

## 🎉 Projeto Configurado!

Após seguir todos os passos, seu projeto estará usando a biblioteca de assinatura reutilizável.

### Estrutura Final:

```
meu-projeto/
├── pages/
│   ├── api/
│   │   ├── webhook.ts              # ✅ Copiado e customizado
│   │   ├── cancel-subscription.ts  # ✅ Copiado e customizado
│   │   └── reactivate-subscription.ts # ✅ Copiado e customizado
│   ├── dashboard.tsx               # ✅ Usa SubscriptionSummary
│   └── assinatura.tsx             # ✅ Usa SubscriptionButton
├── .env.local                      # ✅ Variáveis configuradas
└── package.json                    # ✅ Biblioteca instalada
```

### Tempo Estimado de Setup:
- **Primeiro projeto**: 30-40 minutos
- **Projetos subsequentes**: 15-20 minutos

---

**🚀 Agora você pode replicar o sistema de assinatura em quantos projetos quiser!**