@criapix/saas-assinaturas-client/MIGRATION_GUIDE.md

SDK JavaScript/TypeScript para o AssinaturasService - Sistema de gestão de assinaturas SaaS com processamento de pagamentos de faturas (cartão, PIX, débito), gerenciamento de métodos de pagamento, pagamentos recorrentes e análise de falhas de pagamento

# Guia de Migração - SDK JavaScript do AssinaturasService

## Resumo das Mudanças

O projeto **predin-admin-front** foi migrado para usar o SDK oficial do **saas-core-assinaturas** ao invés de implementações locais duplicadas.

## O que foi feito

### 1. Criado SDK JavaScript/TypeScript

Foi criado um novo SDK JavaScript/TypeScript no repositório `saas-core-assinaturas`:
- **Localização**: `AssinaturasService.SDK.JS/`
- **Pacote NPM**: `@saas-core/assinaturas-client`
- **Baseado no SDK .NET**: Segue a mesma estrutura e API do SDK .NET existente

#### Estrutura do SDK:
```
AssinaturasService.SDK.JS/
├── src/
│   ├── client/
│   │   └── AssinaturasServiceClient.ts
│   ├── types/
│   │   ├── Common.ts
│   │   ├── SubscriptionPlan.ts
│   │   ├── Subscription.ts
│   │   ├── Invoice.ts
│   │   └── index.ts
│   ├── enums/
│   │   ├── SubscriptionStatus.ts
│   │   ├── InvoiceStatus.ts
│   │   ├── BillingCycle.ts
│   │   └── index.ts
│   └── index.ts
├── package.json
├── tsconfig.json
└── README.md
```

### 2. Removido Código Duplicado do predin-admin-front

Foram removidos os seguintes arquivos e diretórios:
- ✅ `src/sdk/assinaturas/client/` (implementação local duplicada)
- ✅ `src/sdk/assinaturas/types/` (tipos locais duplicados)
- ✅ `src/hooks/useAssinaturasSubscriptionPlans.ts` (hooks antigos)
- ✅ `src/hooks/useAssinaturasSubscriptions.ts` (hooks antigos)
- ✅ `src/hooks/useAssinaturasInvoices.ts` (hooks antigos)
- ✅ Métodos de subscription plans do `apiService` (linhas 605-645 de `api.ts`)

### 3. Instalado e Configurado o Novo SDK

#### Dependência Adicionada:
```json
{
  "dependencies": {
    "@saas-core/assinaturas-client": "file:../saas-core-assinaturas/AssinaturasService.SDK.JS"
  }
}
```

#### Novo Módulo de Configuração:
Criado arquivo `src/sdk/assinaturas.ts` que:
- Inicializa o cliente do SDK
- Configura autenticação automática com token do AuthClient
- Exporta funções `createAssinaturasClient()` e `getAssinaturasClient()`
- Re-exporta todos os tipos e enums do SDK

#### Integração com AuthContext:
O cliente é inicializado automaticamente em `AuthContext.tsx`:
```typescript
import { createAssinaturasClient } from '../sdk/assinaturas';

createAssinaturasClient(() => authClient.getAccessToken());
```

### 4. Hooks Atualizados

Foram criados novos hooks que usam o SDK oficial:
- ✅ `src/hooks/useAssinaturasSubscriptionPlans.ts`
- ✅ `src/hooks/useAssinaturasSubscriptions.ts`
- ✅ `src/hooks/useAssinaturasInvoices.ts`
- ✅ `src/hooks/useSubscriptionPlans.ts` (atualizado para usar SDK)

### 5. Variáveis de Ambiente Configuradas

Adicionado `VITE_ASSINATURAS_SERVICE_URL` em todos os arquivos `.env`:

**`.env.development`**:
```env
VITE_ASSINATURAS_SERVICE_URL=http://localhost:5001
```

**`.env.production` e `.env.docker`**:
```env
VITE_ASSINATURAS_SERVICE_URL=VITE_ASSINATURAS_SERVICE_URL_PLACEHOLDER
```

## Mudanças de API

### Antes (usando apiService local):
```typescript
import { apiService } from '@/services/api';

const plans = await apiService.getSubscriptionPlans(filters);
```

### Depois (usando SDK oficial):
```typescript
import { getAssinaturasClient } from '@/sdk/assinaturas';

const client = getAssinaturasClient();
const plans = await client.listSubscriptionPlans(filters);
```

### Usando Hooks:
```typescript
import { useAssinaturasSubscriptionPlans } from '@/hooks/useAssinaturasSubscriptionPlans';

function MyComponent() {
  const { data: plans, isLoading } = useAssinaturasSubscriptionPlans({
    isActive: true,
    page: 1,
    pageSize: 10
  });

  // ...
}
```

## Compatibilidade

Os componentes e páginas existentes **não precisam ser modificados** porque:
- O hook `useSubscriptionPlans()` foi atualizado internamente para usar o SDK
- Os tipos são re-exportados com aliases para manter compatibilidade
- A estrutura de resposta `PaginatedResponse` é compatível

## Próximos Passos

Para usar o SDK em produção:

1. **Configurar URL do serviço** no ambiente de produção/staging
2. **Atualizar docker-compose** para incluir o serviço de assinaturas
3. **Testar autenticação** JWT entre os serviços
4. **Atualizar documentação** de deployment com a nova variável de ambiente

## Benefícios

✅ **Código centralizado**: Uma única implementação do cliente
✅ **Menos duplicação**: Tipos e lógica compartilhados
✅ **Manutenção facilitada**: Mudanças na API refletem automaticamente
✅ **Consistência**: Mesma API em .NET e JavaScript
✅ **Type-safe**: TypeScript com tipos gerados automaticamente

## Suporte

Para dúvidas ou problemas:
- Consulte o [README do SDK](./README.md)
- Verifique a [documentação da API](../AssinaturasService.API/)
- Entre em contato com a equipe SaaS Core