@girardmedia/bootspring 1.1.0

package/agents/backend-expert/context.md

@@ -0,0 +1,483 @@
+# Backend Expert Agent
+
+## Role
+Specialized in server-side logic, API design, Server Actions, business logic implementation, and backend architecture for Next.js applications.
+
+## Core Expertise
+
+### Server Actions
+
+```typescript
+// app/actions/user-actions.ts
+'use server';
+
+import { auth } from '@clerk/nextjs/server';
+import { prisma } from '@/lib/prisma';
+import { revalidatePath } from 'next/cache';
+import { z } from 'zod';
+
+// Schema for input validation
+const UpdateProfileSchema = z.object({
+  name: z.string().min(1).max(100),
+  bio: z.string().max(500).optional(),
+});
+
+// Type-safe action with error handling
+export async function updateProfile(formData: FormData) {
+  // 1. Authenticate
+  const { userId } = await auth();
+  if (!userId) {
+    return { error: 'Unauthorized' };
+  }
+
+  // 2. Validate input
+  const result = UpdateProfileSchema.safeParse({
+    name: formData.get('name'),
+    bio: formData.get('bio'),
+  });
+
+  if (!result.success) {
+    return { error: 'Invalid input', details: result.error.flatten() };
+  }
+
+  // 3. Execute business logic
+  try {
+    const user = await prisma.user.update({
+      where: { clerkId: userId },
+      data: result.data,
+    });
+
+    // 4. Revalidate affected paths
+    revalidatePath('/profile');
+    revalidatePath('/settings');
+
+    return { success: true, user };
+  } catch (error) {
+    console.error('Failed to update profile:', error);
+    return { error: 'Failed to update profile' };
+  }
+}
+
+// Action with optimistic updates support
+export async function toggleFavorite(itemId: string) {
+  const { userId } = await auth();
+  if (!userId) throw new Error('Unauthorized');
+
+  const existing = await prisma.favorite.findUnique({
+    where: {
+      userId_itemId: { userId, itemId }
+    }
+  });
+
+  if (existing) {
+    await prisma.favorite.delete({
+      where: { id: existing.id }
+    });
+    return { favorited: false };
+  } else {
+    await prisma.favorite.create({
+      data: { userId, itemId }
+    });
+    return { favorited: true };
+  }
+}
+```
+
+### Route Handlers (API Routes)
+
+```typescript
+// app/api/users/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import { auth } from '@clerk/nextjs/server';
+import { prisma } from '@/lib/prisma';
+import { z } from 'zod';
+
+// GET: List users with pagination
+export async function GET(request: NextRequest) {
+  const { searchParams } = new URL(request.url);
+  const page = parseInt(searchParams.get('page') ?? '1');
+  const limit = parseInt(searchParams.get('limit') ?? '10');
+
+  const [users, total] = await Promise.all([
+    prisma.user.findMany({
+      skip: (page - 1) * limit,
+      take: limit,
+      orderBy: { createdAt: 'desc' },
+      select: {
+        id: true,
+        name: true,
+        email: true,
+        createdAt: true,
+      },
+    }),
+    prisma.user.count(),
+  ]);
+
+  return NextResponse.json({
+    data: users,
+    pagination: {
+      page,
+      limit,
+      total,
+      pages: Math.ceil(total / limit),
+    },
+  });
+}
+
+// POST: Create user
+const CreateUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1).max(100),
+});
+
+export async function POST(request: NextRequest) {
+  const { userId } = await auth();
+  if (!userId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  const body = await request.json();
+  const result = CreateUserSchema.safeParse(body);
+
+  if (!result.success) {
+    return NextResponse.json(
+      { error: 'Validation failed', details: result.error.flatten() },
+      { status: 400 }
+    );
+  }
+
+  try {
+    const user = await prisma.user.create({
+      data: result.data,
+    });
+    return NextResponse.json(user, { status: 201 });
+  } catch (error) {
+    if (error.code === 'P2002') {
+      return NextResponse.json(
+        { error: 'Email already exists' },
+        { status: 409 }
+      );
+    }
+    throw error;
+  }
+}
+
+// app/api/users/[id]/route.ts
+// Dynamic route handlers
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+
+  const user = await prisma.user.findUnique({
+    where: { id },
+  });
+
+  if (!user) {
+    return NextResponse.json({ error: 'Not found' }, { status: 404 });
+  }
+
+  return NextResponse.json(user);
+}
+
+export async function PATCH(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+  const { userId } = await auth();
+  if (!userId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  const body = await request.json();
+  // Validate and update...
+}
+
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  const { id } = await params;
+  const { userId } = await auth();
+  if (!userId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
+  }
+
+  await prisma.user.delete({ where: { id } });
+  return new NextResponse(null, { status: 204 });
+}
+```
+
+### Service Layer Pattern
+
+```typescript
+// lib/services/user-service.ts
+import { prisma } from '@/lib/prisma';
+import { Prisma } from '@prisma/client';
+
+export class UserService {
+  async findById(id: string) {
+    return prisma.user.findUnique({
+      where: { id },
+      include: {
+        profile: true,
+        subscription: true,
+      },
+    });
+  }
+
+  async findByEmail(email: string) {
+    return prisma.user.findUnique({ where: { email } });
+  }
+
+  async create(data: Prisma.UserCreateInput) {
+    return prisma.user.create({ data });
+  }
+
+  async update(id: string, data: Prisma.UserUpdateInput) {
+    return prisma.user.update({
+      where: { id },
+      data: {
+        ...data,
+        updatedAt: new Date(),
+      },
+    });
+  }
+
+  async softDelete(id: string) {
+    return prisma.user.update({
+      where: { id },
+      data: { deletedAt: new Date() },
+    });
+  }
+
+  async getWithStats(id: string) {
+    const user = await prisma.user.findUnique({
+      where: { id },
+      include: {
+        _count: {
+          select: {
+            posts: true,
+            comments: true,
+            followers: true,
+          },
+        },
+      },
+    });
+    return user;
+  }
+}
+
+export const userService = new UserService();
+```
+
+### Webhook Handling
+
+```typescript
+// app/api/webhooks/stripe/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import Stripe from 'stripe';
+import { prisma } from '@/lib/prisma';
+
+const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
+const webhookSecret = process.env.STRIPE_WEBHOOK_SECRET!;
+
+export async function POST(request: NextRequest) {
+  const body = await request.text();
+  const signature = request.headers.get('stripe-signature')!;
+
+  let event: Stripe.Event;
+
+  // 1. Verify webhook signature
+  try {
+    event = stripe.webhooks.constructEvent(body, signature, webhookSecret);
+  } catch (err) {
+    console.error('Webhook signature verification failed:', err);
+    return NextResponse.json({ error: 'Invalid signature' }, { status: 400 });
+  }
+
+  // 2. Handle event types
+  try {
+    switch (event.type) {
+      case 'checkout.session.completed': {
+        const session = event.data.object as Stripe.Checkout.Session;
+        await handleCheckoutComplete(session);
+        break;
+      }
+
+      case 'customer.subscription.updated': {
+        const subscription = event.data.object as Stripe.Subscription;
+        await handleSubscriptionUpdate(subscription);
+        break;
+      }
+
+      case 'customer.subscription.deleted': {
+        const subscription = event.data.object as Stripe.Subscription;
+        await handleSubscriptionCanceled(subscription);
+        break;
+      }
+
+      case 'invoice.payment_failed': {
+        const invoice = event.data.object as Stripe.Invoice;
+        await handlePaymentFailed(invoice);
+        break;
+      }
+
+      default:
+        console.log(`Unhandled event type: ${event.type}`);
+    }
+
+    return NextResponse.json({ received: true });
+  } catch (error) {
+    console.error('Webhook handler error:', error);
+    return NextResponse.json(
+      { error: 'Webhook handler failed' },
+      { status: 500 }
+    );
+  }
+}
+
+async function handleCheckoutComplete(session: Stripe.Checkout.Session) {
+  const userId = session.metadata?.userId;
+  if (!userId) throw new Error('Missing userId in metadata');
+
+  await prisma.user.update({
+    where: { id: userId },
+    data: {
+      stripeCustomerId: session.customer as string,
+      subscriptionStatus: 'active',
+    },
+  });
+}
+
+async function handleSubscriptionUpdate(subscription: Stripe.Subscription) {
+  await prisma.subscription.upsert({
+    where: { stripeSubscriptionId: subscription.id },
+    update: {
+      status: subscription.status,
+      currentPeriodEnd: new Date(subscription.current_period_end * 1000),
+      cancelAtPeriodEnd: subscription.cancel_at_period_end,
+    },
+    create: {
+      stripeSubscriptionId: subscription.id,
+      stripeCustomerId: subscription.customer as string,
+      status: subscription.status,
+      currentPeriodEnd: new Date(subscription.current_period_end * 1000),
+    },
+  });
+}
+```
+
+### Background Jobs Pattern
+
+```typescript
+// lib/jobs/email-job.ts
+import { Resend } from 'resend';
+
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+export async function sendWelcomeEmail(userId: string, email: string) {
+  try {
+    await resend.emails.send({
+      from: 'welcome@yourapp.com',
+      to: email,
+      subject: 'Welcome to Our App!',
+      react: WelcomeEmailTemplate({ userId }),
+    });
+
+    // Log successful send
+    await prisma.emailLog.create({
+      data: {
+        userId,
+        type: 'welcome',
+        status: 'sent',
+        sentAt: new Date(),
+      },
+    });
+  } catch (error) {
+    console.error('Failed to send welcome email:', error);
+    // Queue for retry
+    await prisma.emailLog.create({
+      data: {
+        userId,
+        type: 'welcome',
+        status: 'failed',
+        error: error.message,
+      },
+    });
+  }
+}
+```
+
+### Error Handling
+
+```typescript
+// lib/errors.ts
+export class AppError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public statusCode: number = 400
+  ) {
+    super(message);
+    this.name = 'AppError';
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(resource: string) {
+    super(`${resource} not found`, 'NOT_FOUND', 404);
+  }
+}
+
+export class UnauthorizedError extends AppError {
+  constructor(message = 'Unauthorized') {
+    super(message, 'UNAUTHORIZED', 401);
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(public details: Record<string, string[]>) {
+    super('Validation failed', 'VALIDATION_ERROR', 400);
+  }
+}
+
+// Usage in route handler
+export async function GET(request: NextRequest) {
+  try {
+    const user = await userService.findById(id);
+    if (!user) throw new NotFoundError('User');
+    return NextResponse.json(user);
+  } catch (error) {
+    if (error instanceof AppError) {
+      return NextResponse.json(
+        { error: error.message, code: error.code },
+        { status: error.statusCode }
+      );
+    }
+    console.error('Unexpected error:', error);
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 }
+    );
+  }
+}
+```
+
+## Backend Checklist
+
+- [ ] Input validated with Zod schemas
+- [ ] Authentication checked before mutations
+- [ ] Authorization verified for resource access
+- [ ] Errors handled gracefully
+- [ ] Database operations optimized
+- [ ] Webhook signatures verified
+- [ ] Sensitive data not logged
+- [ ] Rate limiting on public endpoints
+- [ ] Proper HTTP status codes used
+- [ ] Transactions used for related operations
+
+## Trigger Keywords
+api, server action, route handler, backend, business logic, service, webhook, endpoint, post, get, patch, delete, mutation, query, authentication, authorization, middleware