@polymorphism-tech/morph-spec 4.3.4 → 4.3.6

package/.morph/standards/backend/integrations/asaas/asaas-api.md

@@ -0,0 +1,216 @@
+# Asaas API Integration Standard
+
+> **Scope:** universal
+> **Layer:** 2 (on keyword)
+> **Keywords:** asaas, payment, brazilian, pix, boleto, billing
+> **Load When:** asaas or brazilian payment keywords detected
+
+Brazilian payment gateway integration for PIX, Boleto, and credit card processing.
+
+---
+
+## Overview
+
+Asaas is a Brazilian payment service provider offering:
+- PIX instant payments
+- Boleto bancário
+- Credit card processing
+- Subscription billing
+- Split payments
+
+**Stack:** .NET Backend
+
+---
+
+## Core Principles
+
+1. **Webhook-First**: All payment state changes via webhooks
+2. **Idempotency**: Use idempotency keys for all POST requests
+3. **Security**: Validate webhook signatures, never store full card data
+4. **Brazil-Specific**: Handle CPF/CNPJ validation, Brazilian tax rules
+
+---
+
+## API Configuration
+
+### Environment Variables
+
+```bash
+# .env.local
+ASAAS_API_KEY=your_api_key_here
+ASAAS_WEBHOOK_SECRET=your_webhook_secret
+ASAAS_ENVIRONMENT=sandbox # or production
+```
+
+### TypeScript Client Setup
+
+```typescript
+// lib/asaas/client.ts
+import { createClient } from '@asaas/node-sdk';
+
+export const asaasClient = createClient({
+  apiKey: process.env.ASAAS_API_KEY!,
+  environment: process.env.ASAAS_ENVIRONMENT as 'sandbox' | 'production'
+});
+```
+
+---
+
+## Common Operations
+
+### Create PIX Payment
+
+```typescript
+// app/api/payments/pix/route.ts
+import { asaasClient } from '@/lib/asaas/client';
+
+export async function POST(req: Request) {
+  const { amount, customerId, description } = await req.json();
+
+  const payment = await asaasClient.payments.create({
+    customer: customerId,
+    billingType: 'PIX',
+    value: amount,
+    dueDate: new Date().toISOString().split('T')[0],
+    description,
+  });
+
+  return Response.json({
+    paymentId: payment.id,
+    pixCode: payment.pixTransaction.payload,
+    qrCode: payment.pixTransaction.qrCode.encodedImage
+  });
+}
+```
+
+### Webhook Handler
+
+```typescript
+// app/api/webhooks/asaas/route.ts
+import { headers } from 'next/headers';
+import crypto from 'crypto';
+
+export async function POST(req: Request) {
+  const body = await req.text();
+  const signature = headers().get('asaas-signature');
+
+  // Verify webhook signature
+  const expectedSignature = crypto
+    .createHmac('sha256', process.env.ASAAS_WEBHOOK_SECRET!)
+    .update(body)
+    .digest('hex');
+
+  if (signature !== expectedSignature) {
+    return new Response('Invalid signature', { status: 401 });
+  }
+
+  const event = JSON.parse(body);
+
+  // Handle payment events
+  switch (event.event) {
+    case 'PAYMENT_RECEIVED':
+      await handlePaymentReceived(event.payment);
+      break;
+    case 'PAYMENT_CONFIRMED':
+      await handlePaymentConfirmed(event.payment);
+      break;
+  }
+
+  return new Response('OK');
+}
+```
+
+---
+
+## Database Schema (Supabase)
+
+```sql
+-- Store payment records
+create table payments (
+  id uuid primary key default gen_random_uuid(),
+  user_id uuid references auth.users(id),
+  asaas_payment_id text unique not null,
+  amount decimal(10,2) not null,
+  status text not null, -- pending, confirmed, received
+  billing_type text not null, -- PIX, BOLETO, CREDIT_CARD
+  created_at timestamptz default now(),
+  updated_at timestamptz default now()
+);
+
+-- RLS policies
+alter table payments enable row level security;
+
+create policy "Users read own payments"
+  on payments for select
+  using (auth.uid() = user_id);
+```
+
+---
+
+## Best Practices
+
+### CPF/CNPJ Validation
+
+```typescript
+export function validateCPF(cpf: string): boolean {
+  cpf = cpf.replace(/[^\d]/g, '');
+  if (cpf.length !== 11) return false;
+
+  // Validation logic...
+  return true;
+}
+
+export function validateCNPJ(cnpj: string): boolean {
+  cnpj = cnpj.replace(/[^\d]/g, '');
+  if (cnpj.length !== 14) return false;
+
+  // Validation logic...
+  return true;
+}
+```
+
+### Idempotency Keys
+
+```typescript
+const idempotencyKey = `payment-${userId}-${Date.now()}`;
+
+const payment = await asaasClient.payments.create({
+  // ... payment data
+}, {
+  headers: {
+    'Idempotency-Key': idempotencyKey
+  }
+});
+```
+
+---
+
+## Error Handling
+
+```typescript
+try {
+  const payment = await asaasClient.payments.create(data);
+} catch (error) {
+  if (error.code === 'invalid_cpf') {
+    return Response.json({ error: 'CPF inválido' }, { status: 400 });
+  }
+  if (error.code === 'insufficient_balance') {
+    return Response.json({ error: 'Saldo insuficiente' }, { status: 402 });
+  }
+
+  console.error('Asaas API error:', error);
+  return Response.json({ error: 'Erro no processamento' }, { status: 500 });
+}
+```
+
+---
+
+## References
+
+- [Asaas API Documentation](https://docs.asaas.com/)
+- [Asaas Node SDK](https://github.com/asaas/asaas-node)
+- PIX Specification: Brazilian Central Bank
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/.morph/standards/backend/integrations/clerk/clerk-auth.md

@@ -0,0 +1,290 @@
+# Clerk Authentication Integration Standard
+
+> **Scope:** universal
+> **Layer:** 2 (on keyword)
+> **Keywords:** clerk, auth, authentication, nextjs, user management
+> **Load When:** clerk authentication keywords detected
+
+Modern authentication and user management for Next.js applications.
+
+---
+
+## Overview
+
+Clerk provides:
+- Pre-built UI components (SignIn, SignUp, UserProfile)
+- Social auth (Google, GitHub, etc.)
+- Multi-factor authentication
+- Session management
+- User metadata and organizations
+
+**Primary Use Case:** Next.js 15 + App Router
+
+---
+
+## Core Principles
+
+1. **Server-First**: Use server-side auth checks with `auth()` helper
+2. **Route Protection**: Middleware-based protection for private routes
+3. **Type Safety**: Use Clerk's TypeScript types
+4. **Edge Compatible**: Works with Edge Runtime
+
+---
+
+## Installation & Setup
+
+### Install Packages
+
+```bash
+npm install @clerk/nextjs
+```
+
+### Environment Variables
+
+```bash
+# .env.local
+NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
+CLERK_SECRET_KEY=sk_test_...
+NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
+NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
+NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=/dashboard
+NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=/onboarding
+```
+
+### Root Layout Wrapper
+
+```typescript
+// app/layout.tsx
+import { ClerkProvider } from '@clerk/nextjs';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <ClerkProvider>
+      <html lang="en">
+        <body>{children}</body>
+      </html>
+    </ClerkProvider>
+  );
+}
+```
+
+### Middleware Protection
+
+```typescript
+// middleware.ts
+import { authMiddleware } from '@clerk/nextjs';
+
+export default authMiddleware({
+  publicRoutes: ['/', '/api/webhooks/clerk'],
+  ignoredRoutes: ['/api/public']
+});
+
+export const config = {
+  matcher: ['/((?!.+\\.[\\w]+$|_next).*)', '/', '/(api|trpc)(.*)'],
+};
+```
+
+---
+
+## Common Patterns
+
+### Sign In Page
+
+```typescript
+// app/sign-in/[[...sign-in]]/page.tsx
+import { SignIn } from '@clerk/nextjs';
+
+export default function SignInPage() {
+  return (
+    <div className="flex items-center justify-center min-h-screen">
+      <SignIn />
+    </div>
+  );
+}
+```
+
+### Server-Side Auth Check
+
+```typescript
+// app/dashboard/page.tsx
+import { auth } from '@clerk/nextjs';
+import { redirect } from 'next/navigation';
+
+export default async function DashboardPage() {
+  const { userId } = auth();
+
+  if (!userId) {
+    redirect('/sign-in');
+  }
+
+  return <div>Dashboard for user {userId}</div>;
+}
+```
+
+### Client Component with User Data
+
+```typescript
+// components/UserProfile.tsx
+'use client';
+import { useUser } from '@clerk/nextjs';
+
+export function UserProfile() {
+  const { user, isLoaded, isSignedIn } = useUser();
+
+  if (!isLoaded) return <div>Loading...</div>;
+  if (!isSignedIn) return <div>Not signed in</div>;
+
+  return (
+    <div>
+      <p>Welcome, {user.firstName}!</p>
+      <p>Email: {user.primaryEmailAddress?.emailAddress}</p>
+    </div>
+  );
+}
+```
+
+### API Route Protection
+
+```typescript
+// app/api/protected/route.ts
+import { auth } from '@clerk/nextjs';
+
+export async function GET() {
+  const { userId } = auth();
+
+  if (!userId) {
+    return new Response('Unauthorized', { status: 401 });
+  }
+
+  // Fetch user-specific data
+  const data = await fetchUserData(userId);
+
+  return Response.json(data);
+}
+```
+
+---
+
+## Webhook Integration
+
+### Setup Webhook Endpoint
+
+```typescript
+// app/api/webhooks/clerk/route.ts
+import { Webhook } from 'svix';
+import { headers } from 'next/headers';
+
+export async function POST(req: Request) {
+  const WEBHOOK_SECRET = process.env.CLERK_WEBHOOK_SECRET!;
+
+  const headerPayload = headers();
+  const svix_id = headerPayload.get('svix-id');
+  const svix_timestamp = headerPayload.get('svix-timestamp');
+  const svix_signature = headerPayload.get('svix-signature');
+
+  if (!svix_id || !svix_timestamp || !svix_signature) {
+    return new Response('Missing svix headers', { status: 400 });
+  }
+
+  const payload = await req.json();
+  const body = JSON.stringify(payload);
+
+  const wh = new Webhook(WEBHOOK_SECRET);
+
+  let evt;
+  try {
+    evt = wh.verify(body, {
+      'svix-id': svix_id,
+      'svix-timestamp': svix_timestamp,
+      'svix-signature': svix_signature,
+    });
+  } catch (err) {
+    return new Response('Invalid signature', { status: 400 });
+  }
+
+  // Handle events
+  switch (evt.type) {
+    case 'user.created':
+      await handleUserCreated(evt.data);
+      break;
+    case 'user.updated':
+      await handleUserUpdated(evt.data);
+      break;
+    case 'user.deleted':
+      await handleUserDeleted(evt.data);
+      break;
+  }
+
+  return new Response('OK');
+}
+```
+
+---
+
+## Supabase Integration
+
+### Sync Users to Supabase
+
+```typescript
+// lib/clerk/sync-user.ts
+import { createClient } from '@supabase/supabase-js';
+
+async function handleUserCreated(userData: any) {
+  const supabase = createClient(
+    process.env.NEXT_PUBLIC_SUPABASE_URL!,
+    process.env.SUPABASE_SERVICE_ROLE_KEY!
+  );
+
+  await supabase.from('profiles').insert({
+    clerk_user_id: userData.id,
+    email: userData.email_addresses[0].email_address,
+    first_name: userData.first_name,
+    last_name: userData.last_name,
+    avatar_url: userData.image_url
+  });
+}
+```
+
+---
+
+## Best Practices
+
+### Custom Claims
+
+```typescript
+// Add custom claims in Clerk Dashboard or via API
+const { sessionClaims } = auth();
+const role = sessionClaims?.metadata?.role as string;
+
+if (role !== 'admin') {
+  return new Response('Forbidden', { status: 403 });
+}
+```
+
+### Organizations
+
+```typescript
+import { auth } from '@clerk/nextjs';
+
+const { orgId, orgRole } = auth();
+
+if (!orgId) {
+  redirect('/create-organization');
+}
+
+if (orgRole !== 'admin') {
+  return <div>Admin access required</div>;
+}
+```
+
+---
+
+## References
+
+- [Clerk Next.js Documentation](https://clerk.com/docs/nextjs)
+- [Clerk API Reference](https://clerk.com/docs/reference/backend-api)
+- [Webhooks Guide](https://clerk.com/docs/integrations/webhooks)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*