@quantictech/subscription-components

Biblioteca de componentes React reutilizáveis para sistema de assinatura com Stripe usando arquitetura service-to-service centralizada.

🏗️ Nova Arquitetura (v2.0.0)

Esta versão implementa uma arquitetura centralizada onde:

• Frontend usa a lib para comunicar com o backend da aplicação
• Backend da aplicação faz service-to-service com backend central de pagamentos
• Backend central gerencia toda comunicação com Stripe
• Webhooks são centralizados e roteados para as aplicações

Frontend → Lib NPM → Backend App → Backend Central → Stripe
                                       ↓
                               Webhook Central
                                       ↓
                          Notifica Backends Apps

📦 Instalação

npm install @quantictech/subscription-components

🛠 Configuração

1. No Frontend (React/Next.js)

import { 
  SubscriptionProvider, 
  SubscriptionSummary,
  SubscriptionButton,
  PaymentApiClient 
} from '@quantictech/subscription-components';

// Configurar cliente da API
const paymentClient = new PaymentApiClient({
  baseURL: process.env.NEXT_PUBLIC_API_URL!, // Backend da sua aplicação
  applicationId: 'flashcards', // ID da sua aplicação
  getAuthToken: () => localStorage.getItem('token')
});

function App() {
  return (
    <SubscriptionProvider 
      apiClient={paymentClient}
      stripePublicKey={process.env.NEXT_PUBLIC_STRIPE_KEY!}
    >
      <SubscriptionSummary />
      <SubscriptionButton planId="plan_123" />
    </SubscriptionProvider>
  );
}

2. No Backend da Aplicação (NestJS)

Implemente os endpoints que fazem service-to-service com o backend central:

// payments.controller.ts
@Controller('payments')
export class PaymentsController {
  @Post('create-subscription')
  async createSubscription(@Body() data, @Req() req) {
    const user = req.user; // Já autenticado
    
    // Chamar backend central via service-to-service
    return this.paymentService.createSubscriptionInCentralBackend({
      ...data,
      externalUserId: user.id,
      userEmail: user.email,
      applicationId: 'flashcards'
    });
  }

  @Get('my-subscription')
  async getMySubscription(@Req() req) {
    return this.paymentService.getSubscriptionFromCentralBackend(req.user.id);
  }
}

3. Backend Central de Pagamentos

O backend central (be-saas-payments-v1-nestjs) gerencia:

• Toda comunicação com Stripe
• Webhook único do Stripe
• Notificações para backends das aplicações

📋 Componentes Disponíveis

<SubscriptionSummary />

Exibe resumo da assinatura atual com opções de cancelar/reativar:

<SubscriptionSummary 
  onCancel={(reason) => console.log('Cancelado:', reason)}
  onReactivate={() => console.log('Reativado')}
/>

<SubscriptionButton />

Botão para iniciar nova assinatura:

<SubscriptionButton 
  planId="plan_123"
  buttonText="Assinar Premium"
  onSuccess={(subscription) => console.log('Sucesso!', subscription)}
/>

<StripePaymentElement />

Formulário de pagamento com Stripe Elements:

<StripePaymentElement 
  clientSecret={clientSecret}
  onSuccess={() => console.log('Pagamento confirmado')}
/>

🔧 Hooks Disponíveis

useSubscription()

Hook para gerenciar estado da assinatura:

const {
  subscription,
  loading,
  createSubscription,
  cancelSubscription,
  reactivateSubscription
} = useSubscription();

usePayment()

Hook para gerenciar pagamentos:

const {
  paymentHistory,
  loading,
  createPaymentIntent
} = usePayment();

🎯 Configuração de Ambiente

Frontend (.env.local)

NEXT_PUBLIC_API_URL=https://flashcards-backend.com
NEXT_PUBLIC_STRIPE_KEY=pk_live_...

Backend da Aplicação (.env)

APPLICATION_ID=flashcards
CENTRAL_PAYMENTS_BACKEND_URL=https://be-saas-payments.quantictech.com
SERVICE_JWT_SECRET=seu-secret-compartilhado

Backend Central (.env)

STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
FLASHCARDS_BACKEND_URL=https://flashcards-backend.com
CURRICULUM_BACKEND_URL=https://curriculumai-backend.com

🚀 Vantagens da Nova Arquitetura

• ✅ Centralização: Toda lógica Stripe em um lugar
• ✅ Escalabilidade: Novos produtos = minutos de setup
• ✅ Segurança: Service-to-service com JWT
• ✅ Manutenção: Updates centralizados
• ✅ Compliance: Webhooks únicos e seguros

📚 Documentação Completa

Para templates de implementação e guia detalhado, consulte:

• PUBLISH.md - Guia de publicação e integração
• SECURITY.md - Análise de segurança
• /architecture-templates/ - Templates para backends

🆕 Migração da v1.x

A v2.0.0 introduz breaking changes devido à nova arquitetura:

1. Remover webhooks individuais das aplicações
2. Implementar service-to-service nos backends
3. Configurar backend central de pagamentos
4. Atualizar configuração da lib no frontend

📄 Licença

MIT © QuanticTech