@polymorphism-tech/morph-spec 4.6.0 → 4.7.0

package/.morph/framework/standards/backend/integrations/hangfire/hangfire-jobs.md

@@ -1,350 +0,0 @@
-# Hangfire Background Jobs Standard
-
-> **Scope:** universal
-> **Layer:** 2 (on keyword)
-> **Keywords:** hangfire, background job, recurring, fire-and-forget, scheduled
-> **Load When:** hangfire or background job keywords detected
-
-Background job processing for .NET applications with Hangfire.
-
----
-
-## Overview
-
-Hangfire provides:
-- Fire-and-forget jobs
-- Delayed jobs
-- Recurring jobs (cron schedules)
-- Job continuations
-- Built-in dashboard
-- Retry logic with exponential backoff
-
-**Stack:** .NET 10
-
----
-
-## Core Principles
-
-1. **Stateless Jobs**: Job methods should be stateless and idempotent
-2. **Minimal Dependencies**: Jobs should not depend on HTTP context or scoped services
-3. **Explicit Retries**: Configure retry behavior per job type
-4. **Monitor Dashboard**: Use Hangfire Dashboard for job monitoring
-
----
-
-## Installation & Setup
-
-### Install Packages
-
-```bash
-dotnet add package Hangfire.Core
-dotnet add package Hangfire.SqlServer
-dotnet add package Hangfire.AspNetCore
-```
-
-### Program.cs Configuration
-
-```csharp
-// Program.cs
-using Hangfire;
-using Hangfire.SqlServer;
-
-var builder = WebApplication.CreateBuilder(args);
-
-// Add Hangfire services
-builder.Services.AddHangfire(configuration => configuration
-    .SetDataCompatibilityLevel(CompatibilityLevel.Version_180)
-    .UseSimpleAssemblyNameTypeSerializer()
-    .UseRecommendedSerializerSettings()
-    .UseSqlServerStorage(
-        builder.Configuration.GetConnectionString("HangfireConnection"),
-        new SqlServerStorageOptions
-        {
-            CommandBatchMaxTimeout = TimeSpan.FromMinutes(5),
-            SlidingInvisibilityTimeout = TimeSpan.FromMinutes(5),
-            QueuePollInterval = TimeSpan.Zero,
-            UseRecommendedIsolationLevel = true,
-            DisableGlobalLocks = true
-        }));
-
-builder.Services.AddHangfireServer();
-
-var app = builder.Build();
-
-// Hangfire Dashboard (protect in production!)
-app.UseHangfireDashboard("/hangfire", new DashboardOptions
-{
-    Authorization = new[] { new HangfireAuthorizationFilter() }
-});
-
-app.Run();
-```
-
----
-
-## Job Types
-
-### Fire-and-Forget Jobs
-
-```csharp
-// Enqueue immediately
-BackgroundJob.Enqueue<IEmailService>(x => x.SendWelcomeEmail(userId));
-
-// Alternative: Static method
-BackgroundJob.Enqueue(() => Console.WriteLine("Hello, world!"));
-```
-
-### Delayed Jobs
-
-```csharp
-// Run after 1 hour
-BackgroundJob.Schedule<IReportService>(
-    x => x.GenerateMonthlyReport(),
-    TimeSpan.FromHours(1));
-
-// Run at specific time
-BackgroundJob.Schedule<INotificationService>(
-    x => x.SendReminder(userId),
-    DateTimeOffset.UtcNow.AddDays(7));
-```
-
-### Recurring Jobs
-
-```csharp
-// Run daily at 2 AM UTC
-RecurringJob.AddOrUpdate<ICleanupService>(
-    "cleanup-old-data",
-    x => x.CleanupOldRecords(),
-    Cron.Daily(2));
-
-// Run every 15 minutes
-RecurringJob.AddOrUpdate<ISyncService>(
-    "sync-external-data",
-    x => x.SyncData(),
-    "*/15 * * * *");
-```
-
-### Job Continuations
-
-```csharp
-var parentJobId = BackgroundJob.Enqueue<IOrderService>(
-    x => x.ProcessOrder(orderId));
-
-BackgroundJob.ContinueJobWith<IEmailService>(
-    parentJobId,
-    x => x.SendOrderConfirmation(orderId));
-```
-
----
-
-## Job Service Pattern
-
-```csharp
-// Services/Jobs/IEmailJobService.cs
-public interface IEmailJobService
-{
-    Task SendWelcomeEmailAsync(string userId);
-    Task SendPasswordResetAsync(string email);
-}
-
-// Services/Jobs/EmailJobService.cs
-public class EmailJobService : IEmailJobService
-{
-    private readonly IDbContextFactory<AppDbContext> _dbFactory;
-    private readonly IEmailSender _emailSender;
-
-    public EmailJobService(
-        IDbContextFactory<AppDbContext> dbFactory,
-        IEmailSender emailSender)
-    {
-        _dbFactory = dbFactory;
-        _emailSender = emailSender;
-    }
-
-    public async Task SendWelcomeEmailAsync(string userId)
-    {
-        // Use IDbContextFactory for background jobs
-        await using var db = await _dbFactory.CreateDbContextAsync();
-
-        var user = await db.Users.FindAsync(userId);
-        if (user == null) return;
-
-        await _emailSender.SendAsync(
-            user.Email,
-            "Welcome!",
-            $"Hello {user.Name}!");
-    }
-}
-
-// Register in DI
-builder.Services.AddScoped<IEmailJobService, EmailJobService>();
-```
-
----
-
-## Retry & Error Handling
-
-### Custom Retry Attribute
-
-```csharp
-[AutomaticRetry(Attempts = 3, DelaysInSeconds = new[] { 60, 300, 900 })]
-public async Task ProcessPaymentAsync(string paymentId)
-{
-    // Job logic with automatic retry on failure
-}
-```
-
-### Manual Retry Logic
-
-```csharp
-public async Task SendEmailWithRetryAsync(string email)
-{
-    int maxRetries = 3;
-    int attempt = 0;
-
-    while (attempt < maxRetries)
-    {
-        try
-        {
-            await _emailSender.SendAsync(email, "Subject", "Body");
-            return; // Success
-        }
-        catch (Exception ex)
-        {
-            attempt++;
-            if (attempt >= maxRetries)
-            {
-                // Log and give up
-                _logger.LogError(ex, "Failed to send email after {Attempts} attempts", maxRetries);
-                throw;
-            }
-
-            await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, attempt)));
-        }
-    }
-}
-```
-
----
-
-## Dashboard Authorization
-
-```csharp
-// Filters/HangfireAuthorizationFilter.cs
-using Hangfire.Dashboard;
-
-public class HangfireAuthorizationFilter : IDashboardAuthorizationFilter
-{
-    public bool Authorize(DashboardContext context)
-    {
-        var httpContext = context.GetHttpContext();
-
-        // Allow in development
-        if (httpContext.Request.Host.Host.Contains("localhost"))
-            return true;
-
-        // Require authenticated user with Admin role
-        return httpContext.User.Identity?.IsAuthenticated == true
-            && httpContext.User.IsInRole("Admin");
-    }
-}
-```
-
----
-
-## Best Practices
-
-### Avoid Scoped Services
-
-```csharp
-// ❌ BAD: Don't inject DbContext directly
-public class BadJobService
-{
-    private readonly AppDbContext _db; // Scoped service!
-
-    public BadJobService(AppDbContext db) => _db = db;
-}
-
-// ✅ GOOD: Use IDbContextFactory
-public class GoodJobService
-{
-    private readonly IDbContextFactory<AppDbContext> _dbFactory;
-
-    public GoodJobService(IDbContextFactory<AppDbContext> dbFactory)
-        => _dbFactory = dbFactory;
-
-    public async Task ProcessAsync()
-    {
-        await using var db = await _dbFactory.CreateDbContextAsync();
-        // Use db...
-    }
-}
-```
-
-### Idempotent Jobs
-
-```csharp
-public async Task ProcessOrderAsync(string orderId)
-{
-    await using var db = await _dbFactory.CreateDbContextAsync();
-
-    var order = await db.Orders.FindAsync(orderId);
-    if (order == null || order.Status == OrderStatus.Processed)
-    {
-        // Already processed or doesn't exist - skip
-        return;
-    }
-
-    // Process order...
-    order.Status = OrderStatus.Processed;
-    await db.SaveChangesAsync();
-}
-```
-
----
-
-## Cron Schedule Examples
-
-```csharp
-Cron.Minutely()              // Every minute
-Cron.Hourly()                // Every hour at minute 0
-Cron.Daily()                 // Every day at 00:00 UTC
-Cron.Daily(14)               // Every day at 14:00 UTC
-Cron.Weekly()                // Every Sunday at 00:00 UTC
-Cron.Monthly()               // First day of month at 00:00 UTC
-Cron.Yearly()                // January 1st at 00:00 UTC
-
-// Custom cron
-"*/5 * * * *"                // Every 5 minutes
-"0 */2 * * *"                // Every 2 hours
-"0 9-17 * * 1-5"             // 9 AM to 5 PM, Mon-Fri
-```
-
----
-
-## Monitoring & Troubleshooting
-
-### Dashboard Access
-
-Access the dashboard at `/hangfire` (configured in Program.cs).
-
-### Common Issues
-
-| Issue | Cause | Solution |
-|-------|-------|----------|
-| Jobs not processing | Hangfire server not started | Ensure `AddHangfireServer()` is called |
-| DbContext errors | Using scoped DbContext | Use `IDbContextFactory` |
-| Jobs timing out | Long-running job | Split into smaller jobs with continuations |
-| Memory leaks | Not disposing DbContext | Use `await using` for DbContext |
-
----
-
-## References
-
-- [Hangfire Documentation](https://docs.hangfire.io/)
-- [Hangfire Best Practices](https://docs.hangfire.io/en/latest/best-practices.html)
-- [Cron Expression Generator](https://crontab.guru/)
-
----
-
-*MORPH-SPEC by Polymorphism Tech*

package/.morph/framework/standards/backend/integrations/resend/resend-email.md

@@ -1,385 +0,0 @@
-# Resend Email Service Integration Standard
-
-> **Scope:** universal
-> **Layer:** 2 (on keyword)
-> **Keywords:** resend, email, transactional, smtp, sendgrid alternative
-> **Load When:** resend or transactional email keywords detected
-
-Modern transactional email service for developers, built for Next.js and .NET.
-
----
-
-## Overview
-
-Resend provides:
-- Simple API for sending emails
-- React Email template support
-- Email tracking and analytics
-- Domain verification
-- Webhooks for delivery status
-- 100 free emails/day
-
-**Stack:** Universal (.NET + Next.js)
-
----
-
-## Core Principles
-
-1. **API-First**: Use REST API, not SMTP
-2. **Type Safety**: Use official SDKs with TypeScript/C# types
-3. **Template-Based**: Use React Email for Next.js, Razor for .NET
-4. **Async**: Always send emails asynchronously
-5. **Monitor**: Track delivery status via webhooks
-
----
-
-## Installation & Setup
-
-### Next.js Setup
-
-```bash
-npm install resend react-email
-```
-
-```typescript
-// lib/resend.ts
-import { Resend } from 'resend';
-
-export const resend = new Resend(process.env.RESEND_API_KEY);
-```
-
-### .NET Setup
-
-```bash
-dotnet add package Resend
-```
-
-```csharp
-// Program.cs
-using Resend;
-
-builder.Services.AddResend(options =>
-{
-    options.ApiKey = builder.Configuration["Resend:ApiKey"]!;
-});
-```
-
-### Environment Variables
-
-```bash
-# .env.local (Next.js) or appsettings.json (.NET)
-RESEND_API_KEY=re_...
-RESEND_FROM_EMAIL=noreply@yourdomain.com
-```
-
----
-
-## Next.js Usage
-
-### React Email Template
-
-```tsx
-// emails/WelcomeEmail.tsx
-import { Html, Button, Container, Text } from '@react-email/components';
-
-interface WelcomeEmailProps {
-  name: string;
-  verificationUrl: string;
-}
-
-export default function WelcomeEmail({ name, verificationUrl }: WelcomeEmailProps) {
-  return (
-    <Html>
-      <Container>
-        <Text>Welcome, {name}!</Text>
-        <Button href={verificationUrl}>Verify Email</Button>
-      </Container>
-    </Html>
-  );
-}
-```
-
-### Send Email (API Route)
-
-```typescript
-// app/api/send-welcome/route.ts
-import { resend } from '@/lib/resend';
-import WelcomeEmail from '@/emails/WelcomeEmail';
-
-export async function POST(req: Request) {
-  const { email, name, verificationUrl } = await req.json();
-
-  try {
-    const { data, error } = await resend.emails.send({
-      from: 'MyApp <noreply@yourdomain.com>',
-      to: email,
-      subject: 'Welcome to MyApp!',
-      react: WelcomeEmail({ name, verificationUrl }),
-    });
-
-    if (error) {
-      return Response.json({ error }, { status: 500 });
-    }
-
-    return Response.json({ id: data.id });
-  } catch (error) {
-    return Response.json({ error: 'Failed to send email' }, { status: 500 });
-  }
-}
-```
-
----
-
-## .NET Usage
-
-### Email Service Interface
-
-```csharp
-// Services/IEmailService.cs
-public interface IEmailService
-{
-    Task<string> SendWelcomeEmailAsync(string toEmail, string name);
-    Task<string> SendPasswordResetAsync(string toEmail, string resetUrl);
-}
-```
-
-### Email Service Implementation
-
-```csharp
-// Services/EmailService.cs
-using Resend;
-
-public class EmailService : IEmailService
-{
-    private readonly IResend _resend;
-    private readonly IConfiguration _config;
-
-    public EmailService(IResend resend, IConfiguration config)
-    {
-        _resend = resend;
-        _config = config;
-    }
-
-    public async Task<string> SendWelcomeEmailAsync(string toEmail, string name)
-    {
-        var message = new EmailMessage
-        {
-            From = _config["Resend:FromEmail"]!,
-            To = toEmail,
-            Subject = "Welcome!",
-            HtmlBody = $@"
-                <h1>Welcome, {name}!</h1>
-                <p>Thank you for joining us.</p>
-            "
-        };
-
-        var response = await _resend.EmailSendAsync(message);
-        return response.Id;
-    }
-
-    public async Task<string> SendPasswordResetAsync(string toEmail, string resetUrl)
-    {
-        var message = new EmailMessage
-        {
-            From = _config["Resend:FromEmail"]!,
-            To = toEmail,
-            Subject = "Reset Your Password",
-            HtmlBody = $@"
-                <h1>Password Reset</h1>
-                <p>Click the link below to reset your password:</p>
-                <a href=""{resetUrl}"">Reset Password</a>
-            "
-        };
-
-        var response = await _resend.EmailSendAsync(message);
-        return response.Id;
-    }
-}
-
-// Register in DI
-builder.Services.AddScoped<IEmailService, EmailService>();
-```
-
----
-
-## Batch Emails
-
-### Next.js Batch Send
-
-```typescript
-// Send to multiple recipients
-const { data, error } = await resend.batch.send([
-  {
-    from: 'MyApp <noreply@yourdomain.com>',
-    to: 'user1@example.com',
-    subject: 'Notification',
-    react: NotificationEmail({ message: 'Update 1' }),
-  },
-  {
-    from: 'MyApp <noreply@yourdomain.com>',
-    to: 'user2@example.com',
-    subject: 'Notification',
-    react: NotificationEmail({ message: 'Update 2' }),
-  },
-]);
-```
-
----
-
-## Webhooks for Delivery Status
-
-### Setup Webhook Endpoint
-
-```typescript
-// app/api/webhooks/resend/route.ts
-import { headers } from 'next/headers';
-import { createHmac } from 'crypto';
-
-export async function POST(req: Request) {
-  const body = await req.text();
-  const signature = headers().get('resend-signature');
-
-  // Verify webhook signature
-  const secret = process.env.RESEND_WEBHOOK_SECRET!;
-  const expectedSignature = createHmac('sha256', secret)
-    .update(body)
-    .digest('hex');
-
-  if (signature !== expectedSignature) {
-    return new Response('Invalid signature', { status: 401 });
-  }
-
-  const event = JSON.parse(body);
-
-  switch (event.type) {
-    case 'email.delivered':
-      await handleEmailDelivered(event.data);
-      break;
-    case 'email.bounced':
-      await handleEmailBounced(event.data);
-      break;
-    case 'email.complained':
-      await handleEmailComplained(event.data);
-      break;
-  }
-
-  return new Response('OK');
-}
-```
-
----
-
-## Best Practices
-
-### Background Jobs (with Hangfire)
-
-```csharp
-// Don't block HTTP requests with email sending
-BackgroundJob.Enqueue<IEmailService>(
-    x => x.SendWelcomeEmailAsync(email, name));
-```
-
-### Rate Limiting
-
-```typescript
-// Implement rate limiting for email sends
-import { Ratelimit } from '@upstash/ratelimit';
-import { Redis } from '@upstash/redis';
-
-const ratelimit = new Ratelimit({
-  redis: Redis.fromEnv(),
-  limiter: Ratelimit.slidingWindow(10, '1 h'), // 10 emails per hour
-});
-
-const { success } = await ratelimit.limit(userId);
-if (!success) {
-  return Response.json({ error: 'Rate limit exceeded' }, { status: 429 });
-}
-
-await resend.emails.send({ ... });
-```
-
-### Retry Logic (.NET)
-
-```csharp
-using Polly;
-
-var retryPolicy = Policy
-    .Handle<HttpRequestException>()
-    .WaitAndRetryAsync(3, retryAttempt =>
-        TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)));
-
-await retryPolicy.ExecuteAsync(async () =>
-{
-    await _resend.EmailSendAsync(message);
-});
-```
-
----
-
-## Domain Verification
-
-1. Go to Resend Dashboard → Domains
-2. Add your domain (e.g., `yourdomain.com`)
-3. Add DNS records (SPF, DKIM, DMARC)
-4. Wait for verification (up to 72 hours)
-
-### DNS Records Example
-
-```
-TXT  @  v=spf1 include:resend.com ~all
-TXT  resend._domainkey  <DKIM_VALUE>
-TXT  _dmarc  v=DMARC1; p=none; rua=mailto:dmarc@yourdomain.com
-```
-
----
-
-## Common Email Templates
-
-### Order Confirmation
-
-```tsx
-export default function OrderConfirmation({ orderNumber, total, items }) {
-  return (
-    <Html>
-      <Container>
-        <Text>Order #{orderNumber} Confirmed</Text>
-        <Text>Total: ${total}</Text>
-        <ul>
-          {items.map(item => (
-            <li key={item.id}>{item.name} - ${item.price}</li>
-          ))}
-        </ul>
-      </Container>
-    </Html>
-  );
-}
-```
-
-### Magic Link Auth
-
-```tsx
-export default function MagicLink({ url, expiresIn }) {
-  return (
-    <Html>
-      <Container>
-        <Text>Sign in to your account</Text>
-        <Button href={url}>Sign In</Button>
-        <Text>This link expires in {expiresIn} minutes.</Text>
-      </Container>
-    </Html>
-  );
-}
-```
-
----
-
-## References
-
-- [Resend Documentation](https://resend.com/docs)
-- [React Email](https://react.email/)
-- [Resend .NET SDK](https://github.com/resend/resend-dotnet)
-
----
-
-*MORPH-SPEC by Polymorphism Tech*