@criapix/saas-assinaturas-client/README.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

# AssinaturasService SDK JavaScript/TypeScript

SDK JavaScript/TypeScript para integração com o AssinaturasService - Sistema de gestão de assinaturas SaaS multi-tenant.

## 📦 Instalação

### Via NPM (local link)
```bash
npm install @saas-core/assinaturas-client
```

### Via arquivo local
```bash
npm install file:../saas-core-assinaturas/AssinaturasService.SDK.JS
```

## 🚀 Uso Básico

### Criar e Configurar o Cliente

```typescript
import { AssinaturasServiceClient } from '@saas-core/assinaturas-client';

// Criar instância do cliente
const client = new AssinaturasServiceClient('http://localhost:5001');

// Configurar token de autenticação
client.setAuthorizationToken(jwtToken);
```

### Planos de Assinatura

```typescript
// Listar planos
const plans = await client.listSubscriptionPlans({
  isActive: true,
  page: 1,
  pageSize: 10
});

// Criar plano
const newPlan = await client.createSubscriptionPlan({
  name: 'Plano Básico',
  description: 'Plano básico para pequenos condomínios',
  pricePerUnit: 7.00,
  features: '["Gestão de unidades", "Cobrança mensal"]',
  isDefault: true,
  isActive: true
});

// Atualizar plano
const updatedPlan = await client.updateSubscriptionPlan(planId, {
  name: 'Plano Básico Atualizado',
  pricePerUnit: 8.00
});

// Deletar plano
await client.deleteSubscriptionPlan(planId);
```

### Assinaturas

```typescript
import { BillingCycle } from '@saas-core/assinaturas-client';

// Criar assinatura
const subscription = await client.createSubscription({
  customerId: customerId,
  subscriptionPlanId: planId,
  quantity: 15,
  billingCycle: BillingCycle.Monthly,
  startTrial: false,
  defaultInvoiceDueDayOfMonth: 10
});

// Listar assinaturas
const subscriptions = await client.listSubscriptions({
  customerId: customerId,
  page: 1,
  pageSize: 10
});

// Cancelar assinatura
await client.cancelSubscription(subscriptionId, 'Cliente solicitou cancelamento');
```

### Faturas

```typescript
// Gerar fatura
const invoice = await client.generateInvoice({
  subscriptionId: subscriptionId,
  dueDate: '2024-02-10',
  notes: 'Fatura referente ao mês de Janeiro'
});

// Listar faturas
const invoices = await client.listInvoices({
  subscriptionId: subscriptionId,
  page: 1,
  pageSize: 10
});

// Atualizar status da fatura
import { InvoiceStatus } from '@saas-core/assinaturas-client';

await client.updateInvoiceStatus(invoiceId, {
  status: InvoiceStatus.Paid,
  paidAt: new Date().toISOString(),
  paymentMethod: 'PIX'
});
```

### Processamento de Pagamentos

```typescript
// Processar primeiro pagamento com cartão
const firstPaymentResult = await client.processFirstPayment(invoiceId, {
  cardToken: 'card_token_from_mercadopago',
  cardHolderName: 'João Silva',
  cardExpiryDate: '11/30', // Suporta MM/YY, MM/YYYY ou ISO 8601
  customer: {
    name: 'João Silva',
    email: 'joao@example.com',
    documentNumber: '12345678901',
    phone: '11999999999'
  }
});

// Processar pagamento PIX
const pixResult = await client.processPixPayment(invoiceId, {
  customer: {
    name: 'João Silva',
    email: 'joao@example.com',
    documentNumber: '12345678901'
  }
});

// Processar pagamento com débito
const debitResult = await client.processDebitPayment(invoiceId, {
  cardToken: 'debit_card_token',
  cardHolderName: 'João Silva',
  cardExpiryDate: '05/2032',
  customer: {
    name: 'João Silva',
    email: 'joao@example.com',
    documentNumber: '12345678901'
  }
});

// Atualizar método de pagamento
const updateResult = await client.updatePaymentMethod(subscriptionId, {
  cardToken: 'new_card_token',
  cardHolderName: 'João Silva',
  cardExpiryDate: '12/35',
  customer: {
    name: 'João Silva',
    email: 'joao@example.com',
    documentNumber: '12345678901'
  }
});
```

### Análise de Falhas de Pagamento

```typescript
import {
  PaymentFailureHelper,
  canRetryPayment,
  getSuggestedAction,
  getUserFriendlyReason
} from '@saas-core/assinaturas-client';

// Verificar se um pagamento pode ser tentado novamente
const canRetry = canRetryPayment('insufficient_funds', 'Saldo insuficiente');
// Retorna: true

// Ou usando a classe diretamente
const canRetryAlt = PaymentFailureHelper.canRetryPayment(
  'insufficient_funds',
  'Saldo insuficiente'
);

// Obter ação sugerida para o usuário
const suggestedAction = getSuggestedAction(
  'insufficient_funds',
  'Saldo insuficiente',
  true
);
// Retorna: "Verifique o saldo disponível ou aguarde a próxima tentativa automática"

// Obter mensagem amigável para o usuário
const friendlyMessage = getUserFriendlyReason(
  'expired_card',
  null,
  'Card is expired'
);
// Retorna: "Cartão expirado"

// Exemplo completo com resposta de pagamento falhado
if (paymentResponse.success === false) {
  const canRetry = canRetryPayment(
    paymentResponse.failureCode,
    paymentResponse.failureReason
  );

  const userMessage = getUserFriendlyReason(
    paymentResponse.failureCode,
    paymentResponse.failureReason,
    paymentResponse.errorMessage
  );

  const action = getSuggestedAction(
    paymentResponse.failureCode,
    paymentResponse.failureReason,
    canRetry
  );

  console.log(`Erro: ${userMessage}`);
  console.log(`Ação sugerida: ${action}`);
  console.log(`Pode tentar novamente: ${canRetry ? 'Sim' : 'Não'}`);
}
```

### Validação de Data de Expiração de Cartão

```typescript
import {
  CardExpiryDateValidator,
  isValidCardExpiryDate,
  parseCardExpiryDate,
  normalizeCardExpiryDate
} from '@saas-core/assinaturas-client';

// Validar formato de data
const validationResult = CardExpiryDateValidator.validate('11/30');
if (validationResult.valid) {
  console.log('Data válida:', validationResult.parsedDate);
} else {
  console.error('Erro:', validationResult.error);
}

// Verificação rápida
const isValid = isValidCardExpiryDate('11/30'); // true

// Converter para Date
const expiryDate = parseCardExpiryDate('11/30');

// Normalizar para ISO 8601 (usado internamente pelo SDK)
const isoDate = normalizeCardExpiryDate('11/30');
// Retorna: "2030-11-30T23:59:59.000Z"

// Formatos suportados:
// - "11/30" (MM/YY)
// - "11/2030" (MM/YYYY)
// - "2030-11-30T00:00:00Z" (ISO 8601)
```

## 🔐 Autenticação

O SDK utiliza autenticação JWT via header `Authorization: Bearer {token}`.

```typescript
// Configurar token antes de fazer requisições
client.setAuthorizationToken(jwtToken);
```

O token deve conter as seguintes claims:
- `saasId`: Identificador da aplicação SaaS
- `sub` ou `userId`: ID do usuário
- `role`: Role do usuário (Admin, User, etc.)

## 📚 Tipos Disponíveis

### Enums
- `SubscriptionStatus`: Trial, Active, Suspended, Cancelled, Expired
- `InvoiceStatus`: Pending, Paid, Overdue, Cancelled, Refunded
- `BillingCycle`: Monthly, Quarterly, Yearly

### Interfaces
- `SubscriptionPlanResponse`
- `CreateSubscriptionPlanRequest`
- `UpdateSubscriptionPlanRequest`
- `SubscriptionResponse`
- `InvoiceResponse`
- `PaginatedResponse<T>`

## 🛠️ Build

```bash
npm run build
```

## 📄 Licença

Este projeto é privado e proprietário.