@polymorphism-tech/morph-spec 1.0.0

package/content/.claude/skills/integrations/asaas-financial.md

@@ -0,0 +1,333 @@
+# Asaas Financial
+
+Especialista em integração com Asaas para pagamentos, cobranças e gestão financeira no Brasil.
+
+## Responsabilidades
+
+1. **Integrar Asaas API** para pagamentos
+2. **Criar clientes** e cobranças
+3. **Processar webhooks** de eventos
+4. **Gerenciar assinaturas** recorrentes
+
+## Triggers
+
+Keywords: `asaas`, `payment`, `pix`, `boleto`, `cobranca`, `subscription`, `billing`, `pagamento`
+
+## Sobre o Asaas
+
+- **Plataforma brasileira** de cobranças e pagamentos
+- **Suporta**: PIX, Boleto, Cartão de Crédito
+- **API REST** (sem SDK .NET oficial)
+- **Webhooks** para notificações em tempo real
+
+## Configuração Básica
+
+```csharp
+// appsettings.json
+{
+  "Asaas": {
+    "BaseUrl": "https://sandbox.asaas.com/api/v3",
+    "ApiKey": "${ASAAS_API_KEY}"
+  }
+}
+
+// Services/AsaasOptions.cs
+public class AsaasOptions
+{
+    public string BaseUrl { get; set; } = "";
+    public string ApiKey { get; set; } = "";
+}
+
+// Program.cs
+builder.Services.Configure<AsaasOptions>(
+    builder.Configuration.GetSection("Asaas"));
+
+builder.Services.AddHttpClient<IAsaasClient, AsaasClient>((sp, client) =>
+{
+    var options = sp.GetRequiredService<IOptions<AsaasOptions>>().Value;
+    client.BaseAddress = new Uri(options.BaseUrl);
+    client.DefaultRequestHeaders.Add("access_token", options.ApiKey);
+});
+```
+
+## Cliente HTTP
+
+```csharp
+// Services/AsaasClient.cs
+public interface IAsaasClient
+{
+    Task<AsaasCustomer> CreateCustomerAsync(CreateCustomerRequest request);
+    Task<AsaasPayment> CreatePaymentAsync(CreatePaymentRequest request);
+    Task<AsaasPayment> GetPaymentAsync(string paymentId);
+    Task<AsaasSubscription> CreateSubscriptionAsync(CreateSubscriptionRequest request);
+}
+
+public class AsaasClient : IAsaasClient
+{
+    private readonly HttpClient _httpClient;
+    private readonly ILogger<AsaasClient> _logger;
+
+    public AsaasClient(HttpClient httpClient, ILogger<AsaasClient> logger)
+    {
+        _httpClient = httpClient;
+        _logger = logger;
+    }
+
+    public async Task<AsaasCustomer> CreateCustomerAsync(CreateCustomerRequest request)
+    {
+        var response = await _httpClient.PostAsJsonAsync("customers", request);
+        response.EnsureSuccessStatusCode();
+        return await response.Content.ReadFromJsonAsync<AsaasCustomer>()
+            ?? throw new InvalidOperationException("Failed to deserialize customer");
+    }
+
+    public async Task<AsaasPayment> CreatePaymentAsync(CreatePaymentRequest request)
+    {
+        _logger.LogInformation("Creating payment for customer {CustomerId}", request.Customer);
+
+        var response = await _httpClient.PostAsJsonAsync("payments", request);
+
+        if (!response.IsSuccessStatusCode)
+        {
+            var error = await response.Content.ReadAsStringAsync();
+            _logger.LogError("Failed to create payment: {Error}", error);
+            throw new AsaasException($"Failed to create payment: {error}");
+        }
+
+        return await response.Content.ReadFromJsonAsync<AsaasPayment>()!;
+    }
+
+    public async Task<AsaasPayment> GetPaymentAsync(string paymentId)
+    {
+        var response = await _httpClient.GetAsync($"payments/{paymentId}");
+        response.EnsureSuccessStatusCode();
+        return await response.Content.ReadFromJsonAsync<AsaasPayment>()!;
+    }
+
+    public async Task<AsaasSubscription> CreateSubscriptionAsync(CreateSubscriptionRequest request)
+    {
+        var response = await _httpClient.PostAsJsonAsync("subscriptions", request);
+        response.EnsureSuccessStatusCode();
+        return await response.Content.ReadFromJsonAsync<AsaasSubscription>()!;
+    }
+}
+```
+
+## DTOs
+
+```csharp
+// Models/Asaas/CreateCustomerRequest.cs
+public record CreateCustomerRequest
+{
+    [JsonPropertyName("name")]
+    public required string Name { get; init; }
+
+    [JsonPropertyName("cpfCnpj")]
+    public required string CpfCnpj { get; init; }
+
+    [JsonPropertyName("email")]
+    public string? Email { get; init; }
+
+    [JsonPropertyName("phone")]
+    public string? Phone { get; init; }
+
+    [JsonPropertyName("mobilePhone")]
+    public string? MobilePhone { get; init; }
+}
+
+// Models/Asaas/CreatePaymentRequest.cs
+public record CreatePaymentRequest
+{
+    [JsonPropertyName("customer")]
+    public required string Customer { get; init; }  // Asaas customer ID
+
+    [JsonPropertyName("billingType")]
+    public required string BillingType { get; init; }  // BOLETO, PIX, CREDIT_CARD
+
+    [JsonPropertyName("value")]
+    public required decimal Value { get; init; }
+
+    [JsonPropertyName("dueDate")]
+    public required string DueDate { get; init; }  // yyyy-MM-dd
+
+    [JsonPropertyName("description")]
+    public string? Description { get; init; }
+
+    [JsonPropertyName("externalReference")]
+    public string? ExternalReference { get; init; }  // Seu ID interno
+}
+
+// Models/Asaas/AsaasPayment.cs
+public record AsaasPayment
+{
+    [JsonPropertyName("id")]
+    public string Id { get; init; } = "";
+
+    [JsonPropertyName("customer")]
+    public string Customer { get; init; } = "";
+
+    [JsonPropertyName("value")]
+    public decimal Value { get; init; }
+
+    [JsonPropertyName("status")]
+    public string Status { get; init; } = "";  // PENDING, RECEIVED, CONFIRMED, OVERDUE...
+
+    [JsonPropertyName("billingType")]
+    public string BillingType { get; init; } = "";
+
+    [JsonPropertyName("invoiceUrl")]
+    public string? InvoiceUrl { get; init; }
+
+    [JsonPropertyName("bankSlipUrl")]
+    public string? BankSlipUrl { get; init; }  // URL do boleto
+
+    [JsonPropertyName("pixQrCode")]
+    public AsaasPixQrCode? PixQrCode { get; init; }
+}
+
+public record AsaasPixQrCode
+{
+    [JsonPropertyName("encodedImage")]
+    public string? EncodedImage { get; init; }  // Base64 QR Code
+
+    [JsonPropertyName("payload")]
+    public string? Payload { get; init; }  // PIX copia-e-cola
+}
+```
+
+## Webhooks
+
+```csharp
+// Controllers/AsaasWebhookController.cs
+[ApiController]
+[Route("api/webhooks/asaas")]
+public class AsaasWebhookController : ControllerBase
+{
+    private readonly IPaymentService _paymentService;
+    private readonly ILogger<AsaasWebhookController> _logger;
+
+    public AsaasWebhookController(
+        IPaymentService paymentService,
+        ILogger<AsaasWebhookController> logger)
+    {
+        _paymentService = paymentService;
+        _logger = logger;
+    }
+
+    [HttpPost]
+    public async Task<IActionResult> HandleWebhook([FromBody] AsaasWebhookPayload payload)
+    {
+        _logger.LogInformation("Received Asaas webhook: {Event} for payment {PaymentId}",
+            payload.Event, payload.Payment?.Id);
+
+        try
+        {
+            switch (payload.Event)
+            {
+                case "PAYMENT_CONFIRMED":
+                case "PAYMENT_RECEIVED":
+                    await _paymentService.ConfirmPaymentAsync(payload.Payment!.Id);
+                    break;
+
+                case "PAYMENT_OVERDUE":
+                    await _paymentService.MarkOverdueAsync(payload.Payment!.Id);
+                    break;
+
+                case "PAYMENT_REFUNDED":
+                    await _paymentService.RefundPaymentAsync(payload.Payment!.Id);
+                    break;
+
+                default:
+                    _logger.LogWarning("Unhandled webhook event: {Event}", payload.Event);
+                    break;
+            }
+
+            return Ok();
+        }
+        catch (Exception ex)
+        {
+            _logger.LogError(ex, "Error processing webhook");
+            return StatusCode(500);
+        }
+    }
+}
+
+public record AsaasWebhookPayload
+{
+    [JsonPropertyName("event")]
+    public string Event { get; init; } = "";
+
+    [JsonPropertyName("payment")]
+    public AsaasPayment? Payment { get; init; }
+}
+```
+
+## Assinaturas Recorrentes
+
+```csharp
+// Models/Asaas/CreateSubscriptionRequest.cs
+public record CreateSubscriptionRequest
+{
+    [JsonPropertyName("customer")]
+    public required string Customer { get; init; }
+
+    [JsonPropertyName("billingType")]
+    public required string BillingType { get; init; }
+
+    [JsonPropertyName("value")]
+    public required decimal Value { get; init; }
+
+    [JsonPropertyName("nextDueDate")]
+    public required string NextDueDate { get; init; }
+
+    [JsonPropertyName("cycle")]
+    public required string Cycle { get; init; }  // MONTHLY, WEEKLY, BIWEEKLY, YEARLY
+
+    [JsonPropertyName("description")]
+    public string? Description { get; init; }
+
+    [JsonPropertyName("externalReference")]
+    public string? ExternalReference { get; init; }
+}
+
+// Criar assinatura
+var subscription = await _asaasClient.CreateSubscriptionAsync(new()
+{
+    Customer = customerId,
+    BillingType = "PIX",
+    Value = 49.90m,
+    NextDueDate = DateTime.Today.AddDays(1).ToString("yyyy-MM-dd"),
+    Cycle = "MONTHLY",
+    Description = "Plano Pro",
+    ExternalReference = $"plan_{planId}"
+});
+```
+
+## Ambientes
+
+| Ambiente | Base URL |
+|----------|----------|
+| Sandbox | `https://sandbox.asaas.com/api/v3` |
+| Produção | `https://www.asaas.com/api/v3` |
+
+## Documentação de Referência
+
+- [Asaas API Documentation](https://docs.asaas.com/)
+- [Webhooks](https://docs.asaas.com/reference/webhooks)
+- [Cobranças](https://docs.asaas.com/reference/criar-nova-cobranca)
+- [Assinaturas](https://docs.asaas.com/reference/criar-nova-assinatura)
+
+## Checklist de Integração
+
+- [ ] API Key configurada (não hardcoded)
+- [ ] HttpClient com retry policy (Polly)
+- [ ] Webhook endpoint configurado
+- [ ] Validação de webhook signature
+- [ ] Logs estruturados
+- [ ] Tratamento de erros Asaas
+- [ ] Testes com sandbox
+- [ ] ExternalReference para reconciliação
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/content/.claude/skills/integrations/azure-identity.md

@@ -0,0 +1,309 @@
+# Azure Identity (Microsoft Identity)
+
+Especialista em autenticação com Microsoft Identity Platform para aplicações .NET/Blazor.
+
+## Responsabilidades
+
+1. **Configurar Microsoft Identity** em projetos .NET
+2. **Implementar autenticação** com Azure AD / Entra ID
+3. **Gerenciar tokens** e autorização
+4. **Integrar com APIs** protegidas
+
+## Triggers
+
+Keywords: `identity`, `entra`, `azure ad`, `microsoft auth`, `msal`, `oauth`, `oidc`, `microsoft identity`
+
+## Sobre Microsoft Identity
+
+- **Plataforma oficial** da Microsoft para autenticação
+- **Suporta**: Azure AD, Microsoft accounts, B2C
+- **SDK nativo**: Microsoft.Identity.Web
+- **Ideal para**: Enterprise, Azure-first, Microsoft 365
+
+## Instalação
+
+```bash
+dotnet add package Microsoft.Identity.Web
+dotnet add package Microsoft.Identity.Web.UI  # Para Blazor
+```
+
+## Configuração Básica
+
+```csharp
+// appsettings.json
+{
+  "AzureAd": {
+    "Instance": "https://login.microsoftonline.com/",
+    "Domain": "yourdomain.onmicrosoft.com",
+    "TenantId": "your-tenant-id",
+    "ClientId": "your-client-id",
+    "ClientSecret": "${AZURE_AD_CLIENT_SECRET}",
+    "CallbackPath": "/signin-oidc"
+  }
+}
+
+// Program.cs
+builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
+    .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"));
+
+builder.Services.AddControllersWithViews()
+    .AddMicrosoftIdentityUI();
+
+builder.Services.AddAuthorization();
+
+// Pipeline
+app.UseAuthentication();
+app.UseAuthorization();
+```
+
+## Blazor Server
+
+```csharp
+// Program.cs
+builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
+    .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"));
+
+builder.Services.AddControllersWithViews()
+    .AddMicrosoftIdentityUI();
+
+builder.Services.AddRazorPages();
+builder.Services.AddServerSideBlazor()
+    .AddMicrosoftIdentityConsentHandler();
+
+// App.razor
+<CascadingAuthenticationState>
+    <Router AppAssembly="@typeof(App).Assembly">
+        <Found Context="routeData">
+            <AuthorizeRouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)">
+                <NotAuthorized>
+                    @if (!context.User.Identity?.IsAuthenticated ?? true)
+                    {
+                        <RedirectToLogin />
+                    }
+                    else
+                    {
+                        <p>Você não tem permissão para acessar este recurso.</p>
+                    }
+                </NotAuthorized>
+            </AuthorizeRouteView>
+        </Found>
+    </Router>
+</CascadingAuthenticationState>
+
+// Components/RedirectToLogin.razor
+@inject NavigationManager Navigation
+
+@code {
+    protected override void OnInitialized()
+    {
+        var returnUrl = Uri.EscapeDataString(Navigation.Uri);
+        Navigation.NavigateTo($"MicrosoftIdentity/Account/SignIn?redirectUri={returnUrl}", forceLoad: true);
+    }
+}
+```
+
+## Páginas Protegidas
+
+```razor
+@* Pages/Secure.razor *@
+@page "/secure"
+@attribute [Authorize]
+
+<h1>Área Protegida</h1>
+
+<AuthorizeView>
+    <Authorized>
+        <p>Bem-vindo, @context.User.Identity?.Name!</p>
+        <p>Email: @context.User.FindFirst("preferred_username")?.Value</p>
+    </Authorized>
+</AuthorizeView>
+
+@* Por role *@
+<AuthorizeView Roles="Admin">
+    <Authorized>
+        <AdminPanel />
+    </Authorized>
+</AuthorizeView>
+
+@* Por policy *@
+<AuthorizeView Policy="RequireManagerRole">
+    <Authorized>
+        <ManagerDashboard />
+    </Authorized>
+</AuthorizeView>
+```
+
+## Proteger API
+
+```csharp
+// Program.cs para API
+builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
+    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));
+
+builder.Services.AddAuthorization();
+
+// Controller
+[ApiController]
+[Route("api/[controller]")]
+[Authorize]
+public class ProfileController : ControllerBase
+{
+    [HttpGet]
+    public IActionResult GetProfile()
+    {
+        return Ok(new
+        {
+            UserId = User.FindFirst(ClaimTypes.NameIdentifier)?.Value,
+            Name = User.Identity?.Name,
+            Email = User.FindFirst("preferred_username")?.Value
+        });
+    }
+
+    [HttpGet("admin")]
+    [Authorize(Roles = "Admin")]
+    public IActionResult AdminOnly()
+    {
+        return Ok("Admin access");
+    }
+}
+```
+
+## Chamar APIs Protegidas (Downstream APIs)
+
+```csharp
+// Program.cs
+builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
+    .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"))
+    .EnableTokenAcquisitionToCallDownstreamApi()
+    .AddMicrosoftGraph(builder.Configuration.GetSection("Graph"))
+    .AddInMemoryTokenCaches();
+
+// Service
+public class ProfileService
+{
+    private readonly GraphServiceClient _graphClient;
+
+    public ProfileService(GraphServiceClient graphClient)
+    {
+        _graphClient = graphClient;
+    }
+
+    public async Task<User> GetCurrentUserAsync()
+    {
+        return await _graphClient.Me.GetAsync();
+    }
+
+    public async Task<byte[]?> GetProfilePhotoAsync()
+    {
+        try
+        {
+            var photoStream = await _graphClient.Me.Photo.Content.GetAsync();
+            if (photoStream is null) return null;
+
+            using var memoryStream = new MemoryStream();
+            await photoStream.CopyToAsync(memoryStream);
+            return memoryStream.ToArray();
+        }
+        catch
+        {
+            return null;
+        }
+    }
+}
+```
+
+## Authorization Policies
+
+```csharp
+// Program.cs
+builder.Services.AddAuthorization(options =>
+{
+    options.AddPolicy("RequireAdmin", policy =>
+        policy.RequireRole("Admin"));
+
+    options.AddPolicy("RequireManager", policy =>
+        policy.RequireAssertion(context =>
+            context.User.IsInRole("Admin") ||
+            context.User.IsInRole("Manager")));
+
+    options.AddPolicy("RequireVerifiedEmail", policy =>
+        policy.RequireClaim("email_verified", "true"));
+});
+```
+
+## Multi-tenant
+
+```csharp
+// appsettings.json para multi-tenant
+{
+  "AzureAd": {
+    "Instance": "https://login.microsoftonline.com/",
+    "TenantId": "common",  // ou "organizations" para apenas work accounts
+    "ClientId": "your-client-id",
+    "ClientSecret": "${AZURE_AD_CLIENT_SECRET}"
+  }
+}
+
+// Validar tenant
+builder.Services.Configure<OpenIdConnectOptions>(
+    OpenIdConnectDefaults.AuthenticationScheme,
+    options =>
+    {
+        options.TokenValidationParameters.IssuerValidator = (issuer, token, parameters) =>
+        {
+            // Validar que o tenant é permitido
+            var allowedTenants = new[] { "tenant-id-1", "tenant-id-2" };
+            var tenantId = issuer.Split('/')[3];
+
+            if (!allowedTenants.Contains(tenantId))
+                throw new SecurityTokenInvalidIssuerException("Tenant not allowed");
+
+            return issuer;
+        };
+    });
+```
+
+## Azure AD B2C
+
+```csharp
+// appsettings.json
+{
+  "AzureAdB2C": {
+    "Instance": "https://yourtenant.b2clogin.com",
+    "Domain": "yourtenant.onmicrosoft.com",
+    "TenantId": "your-tenant-id",
+    "ClientId": "your-client-id",
+    "SignUpSignInPolicyId": "B2C_1_signupsignin",
+    "ResetPasswordPolicyId": "B2C_1_passwordreset",
+    "EditProfilePolicyId": "B2C_1_editprofile"
+  }
+}
+
+// Program.cs
+builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
+    .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAdB2C"));
+```
+
+## Documentação de Referência
+
+- [Microsoft Identity Platform](https://learn.microsoft.com/en-us/entra/identity-platform/)
+- [Microsoft.Identity.Web](https://learn.microsoft.com/en-us/entra/msal/dotnet/)
+- [Blazor + Azure AD](https://learn.microsoft.com/en-us/aspnet/core/blazor/security/server/)
+- [Microsoft Graph](https://learn.microsoft.com/en-us/graph/overview)
+- [Azure AD B2C](https://learn.microsoft.com/en-us/azure/active-directory-b2c/)
+
+## Checklist de Integração
+
+- [ ] App registrado no Azure Portal
+- [ ] Client ID e Tenant ID configurados
+- [ ] Client Secret no Key Vault
+- [ ] Redirect URIs configurados
+- [ ] API permissions definidas
+- [ ] Token caching configurado
+- [ ] Authorization policies criadas
+- [ ] Logout flow implementado
+- [ ] Error handling para tokens expirados
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*