@polymorphism-tech/morph-spec 4.5.0 → 4.7.0

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

@@ -1,216 +0,0 @@
-# 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/framework/standards/backend/integrations/clerk/clerk-auth.md

@@ -1,290 +0,0 @@
-# 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*