@polymorphism-tech/morph-spec 2.3.0 → 3.0.0

package/content/.claude/skills/level-2-domains/integrations/asaas-financial.md

@@ -0,0 +1,130 @@
+# Asaas Financial
+
+> **Layer:** 2 | **Load:** on-keyword | **Keywords:** asaas, payment, pix, boleto, cobranca, subscription, billing, pagamento
+
+Integração com Asaas para pagamentos no Brasil. API REST, sem SDK .NET oficial. Suporta PIX, Boleto, Cartão.
+
+## Setup
+
+```csharp
+// appsettings.json
+{ "Asaas": { "BaseUrl": "https://sandbox.asaas.com/api/v3", "ApiKey": "${ASAAS_API_KEY}" } }
+
+// 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);
+    client.DefaultRequestHeaders.Add("User-Agent", "MyApp/1.0");
+});
+```
+
+## Client Interface
+
+```csharp
+public interface IAsaasClient
+{
+    Task<AsaasCustomer> CreateCustomerAsync(CreateCustomerRequest request);
+    Task<AsaasPayment> CreatePaymentAsync(CreatePaymentRequest request);
+    Task<AsaasPayment> GetPaymentAsync(string paymentId);
+    Task<AsaasSubscription> CreateSubscriptionAsync(CreateSubscriptionRequest request);
+}
+```
+
+Implementation: standard `HttpClient.PostAsJsonAsync` / `GetAsync` + `ReadFromJsonAsync` pattern. Log errors, throw `AsaasException` on failure.
+
+## DTOs (all use `[JsonPropertyName]`)
+
+```csharp
+public record CreateCustomerRequest
+{
+    [JsonPropertyName("name")] public required string Name { get; init; }
+    [JsonPropertyName("cpfCnpj")] public required string CpfCnpj { get; init; }  // REQUIRED even in sandbox
+    [JsonPropertyName("email")] public string? Email { get; init; }
+}
+
+public record CreatePaymentRequest
+{
+    [JsonPropertyName("customer")] public required string Customer { get; init; }
+    [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; }
+}
+
+public record AsaasPayment
+{
+    [JsonPropertyName("id")] public string Id { get; init; } = "";
+    [JsonPropertyName("status")] public string Status { get; init; } = "";  // PENDING, RECEIVED, CONFIRMED, OVERDUE
+    [JsonPropertyName("invoiceUrl")] public string? InvoiceUrl { get; init; }
+    [JsonPropertyName("bankSlipUrl")] public string? BankSlipUrl { get; init; }
+    [JsonPropertyName("pixQrCode")] public AsaasPixQrCode? PixQrCode { get; init; }
+}
+
+public record AsaasPixQrCode
+{
+    [JsonPropertyName("encodedImage")] public string? EncodedImage { get; init; }  // Base64
+    [JsonPropertyName("payload")] public string? Payload { get; init; }  // PIX copia-e-cola
+}
+```
+
+Follow same pattern for `CreateSubscriptionRequest` (add `cycle`: MONTHLY/WEEKLY/YEARLY, `nextDueDate`).
+
+## Webhooks
+
+```csharp
+[ApiController, Route("api/webhooks/asaas")]
+public class AsaasWebhookController(IPaymentService payments, ILogger<AsaasWebhookController> logger) : ControllerBase
+{
+    [HttpPost]
+    public async Task<IActionResult> Handle([FromBody] AsaasWebhookPayload payload)
+    {
+        logger.LogInformation("Asaas webhook: {Event} payment {Id}", payload.Event, payload.Payment?.Id);
+        switch (payload.Event)
+        {
+            case "PAYMENT_CONFIRMED": case "PAYMENT_RECEIVED":
+                await payments.ConfirmPaymentAsync(payload.Payment!.Id); break;
+            case "PAYMENT_OVERDUE":
+                await payments.MarkOverdueAsync(payload.Payment!.Id); break;
+            case "PAYMENT_REFUNDED":
+                await payments.RefundPaymentAsync(payload.Payment!.Id); break;
+        }
+        return Ok();
+    }
+}
+```
+
+## Environments
+
+| Environment | Base URL |
+|-------------|----------|
+| Sandbox | `https://sandbox.asaas.com/api/v3` |
+| Production | `https://www.asaas.com/api/v3` |
+
+## Gotchas
+
+| Issue | Fix |
+|-------|-----|
+| PIX QR Code returns Base64, NOT URL | `$"data:image/png;base64,{response.EncodedImage}"` |
+| CPF required even in sandbox | Always include `cpfCnpj` in CreateCustomer |
+| Missing `User-Agent` header | Add to HttpClient defaults |
+| Date format must be `yyyy-MM-dd` | `DateTime.Today.AddDays(1).ToString("yyyy-MM-dd")` |
+
+## Checklist
+
+- [ ] API Key configured (not hardcoded)
+- [ ] HttpClient with retry policy (Polly)
+- [ ] Headers: `access_token` + `User-Agent`
+- [ ] CPF/CNPJ always included for customers
+- [ ] PIX QR Code → data URI conversion
+- [ ] Dates in `yyyy-MM-dd` format
+- [ ] Webhook endpoint + signature validation
+- [ ] ExternalReference for reconciliation
+- [ ] Tests with sandbox
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/content/.claude/skills/level-2-domains/integrations/azure-identity.md

@@ -0,0 +1,142 @@
+# Azure Identity (Microsoft Identity)
+
+> **Layer:** 2 | **Load:** on-keyword | **Keywords:** identity, entra, azure ad, microsoft auth, msal, oauth, oidc, microsoft identity
+
+Microsoft Identity Platform for .NET/Blazor. SDK: `Microsoft.Identity.Web`.
+
+## Setup
+
+```bash
+dotnet add package Microsoft.Identity.Web
+dotnet add package Microsoft.Identity.Web.UI  # For Blazor
+```
+
+```json
+// 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"
+} }
+```
+
+```csharp
+// Program.cs
+builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
+    .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"));
+builder.Services.AddControllersWithViews().AddMicrosoftIdentityUI();
+builder.Services.AddAuthorization();
+app.UseAuthentication();
+app.UseAuthorization();
+```
+
+## Blazor Server
+
+```csharp
+// Additional setup
+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>No permission.</p> }
+                </NotAuthorized>
+            </AuthorizeRouteView>
+        </Found>
+    </Router>
+</CascadingAuthenticationState>
+
+// RedirectToLogin.razor
+@inject NavigationManager Nav
+@code {
+    protected override void OnInitialized() =>
+        Nav.NavigateTo($"MicrosoftIdentity/Account/SignIn?redirectUri={Uri.EscapeDataString(Nav.Uri)}", forceLoad: true);
+}
+```
+
+## Protected Pages
+
+```razor
+@page "/secure"
+@attribute [Authorize]
+
+<AuthorizeView>
+    <Authorized>Welcome, @context.User.Identity?.Name!</Authorized>
+</AuthorizeView>
+
+<AuthorizeView Roles="Admin"><Authorized><AdminPanel /></Authorized></AuthorizeView>
+```
+
+## API Protection
+
+```csharp
+// API Program.cs
+builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
+    .AddMicrosoftIdentityWebApi(builder.Configuration.GetSection("AzureAd"));
+
+// Controller
+[ApiController, Route("api/[controller]"), Authorize]
+public class ProfileController : ControllerBase
+{
+    [HttpGet]
+    public IActionResult GetProfile() => Ok(new {
+        UserId = User.FindFirst(ClaimTypes.NameIdentifier)?.Value,
+        Name = User.Identity?.Name
+    });
+
+    [HttpGet("admin"), Authorize(Roles = "Admin")]
+    public IActionResult AdminOnly() => Ok("Admin access");
+}
+```
+
+## Downstream APIs (Microsoft Graph)
+
+```csharp
+builder.Services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
+    .AddMicrosoftIdentityWebApp(builder.Configuration.GetSection("AzureAd"))
+    .EnableTokenAcquisitionToCallDownstreamApi()
+    .AddMicrosoftGraph(builder.Configuration.GetSection("Graph"))
+    .AddInMemoryTokenCaches();
+```
+
+## Authorization Policies
+
+```csharp
+builder.Services.AddAuthorization(o => {
+    o.AddPolicy("RequireAdmin", p => p.RequireRole("Admin"));
+    o.AddPolicy("RequireManager", p => p.RequireAssertion(c =>
+        c.User.IsInRole("Admin") || c.User.IsInRole("Manager")));
+});
+```
+
+## Multi-tenant & B2C
+
+```json
+// Multi-tenant: TenantId = "common" or "organizations"
+// Then validate allowed tenants in TokenValidationParameters.IssuerValidator
+
+// B2C: Use "AzureAdB2C" section with SignUpSignInPolicyId, ResetPasswordPolicyId
+```
+
+## Checklist
+
+- [ ] App registered in Azure Portal
+- [ ] Client ID + Tenant ID configured
+- [ ] Client Secret in Key Vault
+- [ ] Redirect URIs configured
+- [ ] API permissions defined
+- [ ] Token caching configured
+- [ ] Authorization policies created
+- [ ] Logout flow implemented
+- [ ] Token expiry error handling
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/content/.claude/skills/level-2-domains/integrations/clerk-auth.md

@@ -0,0 +1,108 @@
+# Clerk Auth
+
+> **Layer:** 2 | **Load:** on-keyword | **Keywords:** clerk, auth, login, signup, authentication, session, jwt, user
+
+Autenticação SaaS com Clerk para .NET/Blazor. SDK: `Clerk.Net.AspNetCore.Security`.
+
+## Setup
+
+```csharp
+// appsettings.json
+{ "Clerk": { "SecretKey": "${CLERK_SECRET_KEY}", "PublishableKey": "pk_test_xxx" } }
+
+// Program.cs
+builder.Services.AddClerk(builder.Configuration);
+builder.Services.AddAuthentication(ClerkAuthenticationDefaults.AuthenticationScheme)
+    .AddClerk(o => { o.Authority = "https://clerk.{instance}.com"; o.ValidAudiences = ["your-app-id"]; });
+builder.Services.AddAuthorization();
+app.UseAuthentication();
+app.UseAuthorization();
+```
+
+## Protected Endpoints
+
+```csharp
+// Minimal API
+app.MapGet("/api/profile", async (ClaimsPrincipal user, IClerkClient clerk) =>
+{
+    var userId = user.FindFirstValue(ClaimTypes.NameIdentifier);
+    if (userId is null) return Results.Unauthorized();
+    var u = await clerk.Users.GetUserAsync(userId);
+    return Results.Ok(new { u.Id, Email = u.EmailAddresses.FirstOrDefault()?.EmailAddress });
+}).RequireAuthorization();
+
+// Controller: same pattern with [Authorize] + User.FindFirstValue()
+// Role-based: [Authorize(Roles = "admin")]
+```
+
+## Blazor Server
+
+> **Ref:** Same `CascadingAuthenticationState` + `AuthorizeRouteView` pattern as `azure-identity.md`
+
+```razor
+@* RedirectToLogin.razor *@
+@inject NavigationManager Nav
+@code {
+    protected override void OnInitialized() =>
+        Nav.NavigateTo($"/sign-in?redirect_url={Uri.EscapeDataString(Nav.Uri)}", forceLoad: true);
+}
+
+@* Protected page *@
+@page "/dashboard"
+@attribute [Authorize]
+<AuthorizeView><Authorized>Welcome, @context.User.Identity?.Name!</Authorized></AuthorizeView>
+<AuthorizeView Roles="admin"><Authorized><AdminPanel /></Authorized></AuthorizeView>
+```
+
+## Client Operations
+
+```csharp
+var user = await _clerk.Users.GetUserAsync(userId);                    // Get
+var users = await _clerk.Users.GetUserListAsync(new() { Limit = 10 }); // List
+await _clerk.Users.UpdateUserMetadataAsync(userId, new()               // Update metadata
+    { PublicMetadata = new Dictionary<string, object> { ["plan"] = "pro" } });
+await _clerk.Users.DeleteUserAsync(userId);                            // Delete
+```
+
+## Webhooks
+
+```csharp
+[ApiController, Route("api/webhooks/clerk")]
+public class ClerkWebhookController(IUserService users) : ControllerBase
+{
+    [HttpPost]
+    public async Task<IActionResult> Handle([FromBody] ClerkWebhookPayload payload)
+    {
+        switch (payload.Type)
+        {
+            case "user.created": await users.SyncUserAsync(payload.Data); break;
+            case "user.updated": await users.UpdateUserAsync(payload.Data); break;
+            case "user.deleted": await users.DeleteUserAsync(payload.Data.Id); break;
+        }
+        return Ok();
+    }
+}
+```
+
+## Clerk vs Azure Identity
+
+| Aspecto | Clerk | Azure Identity |
+|---------|-------|----------------|
+| Setup | Faster | More complex |
+| Cost | Freemium (5k MAU free) | Free (Azure AD) |
+| Social login | 20+ providers | Limited |
+| UI components | Pre-built | Build your own |
+| Best for | SaaS B2C, MVPs | Enterprise/Azure |
+
+## Checklist
+
+- [ ] Secret Key in Key Vault (not hardcoded)
+- [ ] Authentication scheme configured
+- [ ] Authorization policies defined
+- [ ] Webhook endpoint + signature validation
+- [ ] Redirect after login configured
+- [ ] Error handling for expired sessions
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/content/.claude/skills/level-2-domains/integrations/resend-email.md

@@ -0,0 +1,119 @@
+# Resend Email
+
+> **Layer:** 2 | **Load:** on-keyword | **Keywords:** resend, email, envio, transactional, notification, send email, template
+
+Transactional email via Resend for .NET. REST API, no official SDK. Simple, developer-friendly.
+
+## Setup
+
+```csharp
+// appsettings.json
+{ "Resend": { "BaseUrl": "https://api.resend.com", "ApiKey": "${RESEND_API_KEY}", "FromEmail": "noreply@yourdomain.com" } }
+
+// Program.cs
+builder.Services.Configure<ResendOptions>(builder.Configuration.GetSection("Resend"));
+builder.Services.AddHttpClient<IResendClient, ResendClient>((sp, client) =>
+{
+    var options = sp.GetRequiredService<IOptions<ResendOptions>>().Value;
+    client.BaseAddress = new Uri(options.BaseUrl);
+    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", options.ApiKey);
+});
+```
+
+## Client Interface
+
+```csharp
+public interface IResendClient
+{
+    Task<EmailResponse> SendAsync(SendEmailRequest request, CancellationToken ct = default);
+    Task<EmailResponse> SendBatchAsync(IEnumerable<SendEmailRequest> requests, CancellationToken ct = default);
+    Task<EmailDetails> GetEmailAsync(string emailId, CancellationToken ct = default);
+}
+```
+
+Implementation: `HttpClient.PostAsJsonAsync("/emails")` + `ReadFromJsonAsync<EmailResponse>`. Log errors, throw `ResendException` on failure.
+
+## DTOs
+
+```csharp
+public record SendEmailRequest
+{
+    [JsonPropertyName("from")] public required string From { get; init; }
+    [JsonPropertyName("to")] public required string[] To { get; init; }
+    [JsonPropertyName("subject")] public required string Subject { get; init; }
+    [JsonPropertyName("html")] public string? Html { get; init; }
+    [JsonPropertyName("text")] public string? Text { get; init; }
+    [JsonPropertyName("reply_to")] public string? ReplyTo { get; init; }
+    [JsonPropertyName("tags")] public Tag[]? Tags { get; init; }
+}
+
+public record EmailResponse
+{
+    [JsonPropertyName("id")] public string Id { get; init; } = "";
+}
+
+public record Tag
+{
+    [JsonPropertyName("name")] public required string Name { get; init; }
+    [JsonPropertyName("value")] public required string Value { get; init; }
+}
+```
+
+## Webhooks
+
+```csharp
+[ApiController, Route("api/webhooks/resend")]
+public class ResendWebhookController(IEmailTrackingService tracking, ILogger<ResendWebhookController> logger) : ControllerBase
+{
+    [HttpPost]
+    public async Task<IActionResult> Handle([FromBody] ResendWebhookPayload payload)
+    {
+        logger.LogInformation("Resend webhook: {Type} for {EmailId}", payload.Type, payload.Data?.EmailId);
+        switch (payload.Type)
+        {
+            case "email.delivered": await tracking.MarkDeliveredAsync(payload.Data!.EmailId); break;
+            case "email.bounced": await tracking.MarkBouncedAsync(payload.Data!.EmailId); break;
+            case "email.complained": await tracking.MarkComplainedAsync(payload.Data!.EmailId); break;
+        }
+        return Ok();
+    }
+}
+```
+
+## Abstraction Pattern
+
+```csharp
+// Use IEmailService abstraction over IResendClient for testability
+public interface IEmailService
+{
+    Task<string> SendTransactionalAsync(string to, string subject, string htmlBody, CancellationToken ct = default);
+}
+
+// ResendEmailService implements IEmailService using IResendClient
+// FakeEmailClient implements IEmailService for simulation mode
+```
+
+## Gotchas
+
+| Issue | Fix |
+|-------|-----|
+| Rate limit: 100 req/sec (free), 1000 (pro) | Queue emails via Hangfire for bulk sends |
+| Domain verification required for production | Verify in Resend dashboard, add DNS records |
+| `from` must match verified domain | Use `noreply@yourdomain.com` |
+| HTML email rendering varies | Test with Litmus/Email on Acid, use MJML |
+| Webhook signature validation | Verify `svix-signature` header in production |
+
+## Checklist
+
+- [ ] API Key in Key Vault (not hardcoded)
+- [ ] HttpClient with `Authorization: Bearer` header
+- [ ] Domain verified in Resend dashboard
+- [ ] `IEmailService` abstraction for testability
+- [ ] Webhook endpoint + signature validation
+- [ ] Rate limiting handled (queue for bulk)
+- [ ] Tags used for tracking/analytics
+- [ ] Simulation mode (`FakeEmailClient`) for dev
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*