# @birhaus/compliance

**Regulatory compliance and audit trail components for BIRHAUS design system**

[![npm version](https://badge.fury.io/js/@birhaus%2Fcompliance.svg)](https://badge.fury.io/js/@birhaus%2Fcompliance)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![Spanish-First](https://img.shields.io/badge/Spanish--First-✓-green.svg)](#spanish-first-design)
[![SEPRELAD](https://img.shields.io/badge/SEPRELAD-Compliant-yellow.svg)](#seprelad-compliance)
[![GDPR](https://img.shields.io/badge/GDPR-Ready-blue.svg)](#gdpr-compliance)

Comprehensive React components for regulatory compliance, audit trails, and privacy management with built-in support for SEPRELAD, GDPR, and Spanish-first documentation.

## 🚀 Features

- **🏛️ SEPRELAD Compliance** - Paraguay financial reporting automation
- **🔒 GDPR Privacy Controls** - European privacy regulation support  
- **📋 Audit Trails** - Complete action logging and timeline visualization
- **🇪🇸 Spanish-First** - Primary Spanish interface with regulatory terminology
- **📊 Regulatory Reports** - Automated compliance report generation
- **🔍 Privacy Management** - User consent and data protection tools
- **♿ Accessibility** - WCAG AA+ compliant components
- **⚡ Real-time Monitoring** - Live compliance violation detection
- **📱 Responsive** - Mobile-optimized compliance interfaces

## 📦 Installation

```bash
npm install @birhaus/compliance

# Peer dependencies
npm install react react-dom @birhaus/tokens @birhaus/primitives @birhaus/provider
```

## 🎯 Quick Start

```tsx
import { 
  BirhausAuditTrail,
  BirhausPrivacyManager, 
  BirhausSEPRELADDashboard 
} from '@birhaus/compliance'

function ComplianceDashboard() {
  return (
    <div>
      {/* SEPRELAD Financial Compliance */}
      <BirhausSEPRELADDashboard
        transactions={transactionData}
        showAlerts={true}
        autoReport={true}
        locale="es-PY"
      />
      
      {/* Audit Trail Visualization */}
      <BirhausAuditTrail
        events={auditEvents}
        showFilters={true}
        titleEs="Registro de Actividades"
        exportFormats={['pdf', 'csv']}
      />
      
      {/* Privacy & GDPR Controls */}
      <BirhausPrivacyManager
        userConsents={userConsentData}
        showGDPRControls={true}
        allowDataExport={true}
        privacyPolicy="/privacy-policy"
      />
    </div>
  )
}
```

## 📋 Components

| Component | Purpose | Compliance Standards |
|-----------|---------|---------------------|
| **BirhausSEPRELADDashboard** | Paraguay financial reporting | SEPRELAD, Anti-Money Laundering |
| **BirhausAuditTrail** | Action logging & timeline | SOX, ISO 27001, Audit Standards |
| **BirhausPrivacyManager** | GDPR privacy controls | GDPR, CCPA, Data Protection |
| **BirhausComplianceChecklist** | Regulatory requirement tracking | Custom compliance frameworks |
| **BirhausRegulatoryReport** | Automated report generation | Multiple regulatory standards |

## 🏛️ SEPRELAD Dashboard

Complete Paraguay financial compliance automation:

```tsx
import { BirhausSEPRELADDashboard } from '@birhaus/compliance'

function FinancialCompliance() {
  const transactions = [
    {
      id: '1',
      monto: 15000, // USD - triggers SEPRELAD reporting
      moneda: 'USD',
      tipo: 'transferencia',
      fecha: new Date(),
      origen: 'Juan Pérez',
      destino: 'María González',
      documentoIdentidad: '1.234.567'
    }
  ]

  return (
    <BirhausSEPRELADDashboard
      transactions={transactions}
      
      // Automatic threshold monitoring
      thresholdUSD={10000} // SEPRELAD threshold
      autoReport={true}    // Generate reports automatically
      
      // Real-time alerts
      showAlerts={true}
      alertTypes={['threshold', 'suspicious', 'incomplete']}
      
      // Spanish-first reporting
      reportLanguage="es"
      includeSpanishSummary={true}
      
      // Export capabilities
      showExport={true}
      exportFormats={['pdf', 'excel', 'csv']}
      
      // Audit integration
      onComplianceEvent={(event) => {
        console.log('SEPRELAD event:', event)
        // Log to audit trail
      }}
    />
  )
}
```

### SEPRELAD Features

- **✅ Threshold Monitoring** - Automatic USD conversion and reporting
- **✅ Suspicious Activity Detection** - Pattern analysis for unusual transactions
- **✅ Document Validation** - CI, RUC, and passport verification
- **✅ Report Generation** - Official SEPRELAD format reports
- **✅ Spanish Documentation** - All reports in Spanish as required
- **✅ Real-time Alerts** - Immediate notification of reportable events

```tsx
// Advanced SEPRELAD Configuration
<BirhausSEPRELADDashboard
  transactions={transactions}
  
  // Advanced monitoring
  suspiciousPatterns={{
    rapidTransfers: { limit: 5, timeframe: '1h' },
    roundNumbers: true,
    structuring: { threshold: 9500 }
  }}
  
  // Regulatory settings
  reportingEntity={{
    name: 'Banco Nacional de Paraguay',
    code: 'BNP001',
    supervisor: 'SEPRELAD'
  }}
  
  // Automatic escalation
  escalationRules={{
    amount: 50000, // USD
    frequency: 10,  // transactions per day
    alertEmail: 'compliance@bank.py'
  }}
/>
```

## 📋 Audit Trail

Complete audit trail visualization with Spanish-first documentation:

```tsx
import { BirhausAuditTrail } from '@birhaus/compliance'

function AuditPage() {
  const auditEvents = [
    {
      id: '1',
      timestamp: '2024-08-21T10:30:00Z',
      actor: 'María García',
      actorId: 'user_123',
      action: 'transferencia.creada',
      entity: 'transferencia',
      entityId: 'trans_456',
      details: {
        monto: 500000,
        moneda: 'PYG',
        destino: 'Juan Pérez'
      },
      ipAddress: '192.168.1.100',
      userAgent: 'Mozilla/5.0...',
      status: 'success'
    }
  ]

  return (
    <BirhausAuditTrail
      events={auditEvents}
      
      // Spanish-first interface
      titleEs="Registro de Auditoría"
      titleEn="Audit Trail"
      emptyMessage="No hay actividades registradas"
      
      // Filtering capabilities
      showFilters={true}
      filters={{
        dateRange: true,
        actor: true,
        action: true,
        status: true
      }}
      
      // Search functionality  
      showSearch={true}
      searchFields={['actor', 'action', 'entity']}
      
      // Export options
      showExport={true}
      exportFormats={['pdf', 'csv', 'json']}
      
      // Real-time updates
      realTime={true}
      refreshInterval={30000} // 30 seconds
      
      // Compliance features
      showIntegrityCheck={true}
      signEvents={true} // Digital signatures
    />
  )
}
```

### Audit Trail Features

- **🔍 Search & Filter** - Find specific events quickly
- **📊 Timeline View** - Chronological event visualization  
- **🔐 Integrity Protection** - Tamper-evident audit logs
- **📱 Mobile Optimized** - Touch-friendly audit review
- **⚡ Real-time Updates** - Live event streaming
- **📄 Export Options** - Multiple format support

## 🔒 Privacy Manager

GDPR-compliant privacy controls and user consent management:

```tsx
import { BirhausPrivacyManager } from '@birhaus/compliance'

function PrivacyDashboard() {
  const userConsents = [
    {
      userId: 'user_123',
      name: 'María García',
      email: 'maria@example.com',
      consents: {
        marketing: { granted: true, date: '2024-01-15' },
        analytics: { granted: false, date: '2024-01-15' },
        cookies: { granted: true, date: '2024-01-15' }
      },
      dataRequests: [
        {
          type: 'access',
          date: '2024-02-01',
          status: 'completed'
        }
      ]
    }
  ]

  return (
    <BirhausPrivacyManager
      userConsents={userConsents}
      
      // GDPR compliance
      showGDPRControls={true}
      gdprOptions={{
        allowDataAccess: true,
        allowDataPortability: true,
        allowDataDeletion: true,
        allowConsentWithdrawal: true
      }}
      
      // Spanish-first privacy
      privacyLabels={{
        dataAccess: { es: 'Acceso a Datos', en: 'Data Access' },
        dataPortability: { es: 'Portabilidad', en: 'Portability' },
        dataDeletion: { es: 'Eliminación', en: 'Deletion' }
      }}
      
      // Cookie management
      cookieCategories={[
        { key: 'essential', required: true, nameEs: 'Esenciales' },
        { key: 'analytics', required: false, nameEs: 'Analíticas' },
        { key: 'marketing', required: false, nameEs: 'Marketing' }
      ]}
      
      // Privacy policy integration
      privacyPolicyUrl="/politica-privacidad"
      termsOfServiceUrl="/terminos-servicio"
      
      // Audit integration
      onPrivacyEvent={(event) => {
        console.log('Privacy event:', event)
        // Log privacy actions for audit
      }}
    />
  )
}
```

### GDPR Features

- **✅ Consent Management** - Granular user consent tracking
- **✅ Data Access Requests** - "Right to know" implementation
- **✅ Data Portability** - Export user data in standard formats
- **✅ Data Deletion** - "Right to be forgotten" automation
- **✅ Cookie Controls** - Granular cookie category management
- **✅ Privacy Audit** - Complete privacy action logging

## 📊 Regulatory Reports

Automated compliance report generation:

```tsx
import { BirhausRegulatoryReport } from '@birhaus/compliance'

function ComplianceReporting() {
  return (
    <BirhausRegulatoryReport
      reportType="seprelad-monthly"
      
      // Data sources
      transactions={transactionData}
      entities={entityData}
      timeRange={{
        start: new Date('2024-08-01'),
        end: new Date('2024-08-31')
      }}
      
      // Report configuration
      includeGraphs={true}
      includeSummary={true}
      language="es" // Spanish-first reports
      
      // Template customization
      template={{
        logo: '/company-logo.png',
        header: 'Reporte Mensual SEPRELAD',
        footer: 'Documento Confidencial'
      }}
      
      // Export settings
      exportFormats={['pdf', 'excel']}
      autoEmail={{
        recipients: ['compliance@company.py'],
        subject: 'Reporte Mensual SEPRELAD - Agosto 2024'
      }}
      
      // Compliance validation
      validateBeforeExport={true}
      requiredFields={['entityName', 'reportingPeriod', 'transactionSummary']}
    />
  )
}
```

## ✅ Compliance Checklist

Track regulatory requirements across multiple frameworks:

```tsx
import { BirhausComplianceChecklist } from '@birhaus/compliance'

function ComplianceTracking() {
  const requirements = [
    {
      id: 'seprelad-1',
      framework: 'SEPRELAD',
      requirement: 'Reportar transacciones > $10,000 USD',
      status: 'compliant',
      lastChecked: '2024-08-21',
      evidence: '/docs/seprelad-report-aug-2024.pdf'
    },
    {
      id: 'gdpr-1',
      framework: 'GDPR',
      requirement: 'Política de privacidad actualizada',
      status: 'pending',
      dueDate: '2024-09-01',
      assignee: 'Legal Team'
    }
  ]

  return (
    <BirhausComplianceChecklist
      requirements={requirements}
      
      // Framework filtering
      frameworks={['SEPRELAD', 'GDPR', 'SOX', 'ISO27001']}
      showFrameworkFilter={true}
      
      // Status tracking
      statusTypes={{
        compliant: { color: 'green', labelEs: 'Cumpliendo' },
        pending: { color: 'yellow', labelEs: 'Pendiente' },
        overdue: { color: 'red', labelEs: 'Vencido' }
      }}
      
      // Progress visualization
      showProgressBar={true}
      groupBy="framework"
      
      // Action management
      allowAddRequirement={true}
      allowStatusUpdate={true}
      allowEvidenceUpload={true}
      
      // Notifications
      sendReminders={true}
      reminderDays={[30, 7, 1]} // Days before due date
    />
  )
}
```

## 🔐 Data Protection Utilities

Additional utilities for data protection compliance:

```tsx
import { 
  encryptSensitiveData,
  anonymizeUserData,
  validateDataRetention,
  generatePrivacyReport 
} from '@birhaus/compliance'

// Data encryption for storage
const encryptedData = encryptSensitiveData(userData, {
  algorithm: 'AES-256-GCM',
  keyRotation: true
})

// User data anonymization
const anonymizedData = anonymizeUserData(userData, {
  preserveFields: ['id', 'createdAt'],
  anonymizeFields: ['name', 'email', 'phone'],
  strategy: 'pseudonymization' // or 'randomization'
})

// Data retention compliance
const retentionCheck = validateDataRetention(dataset, {
  retentionPeriod: '7 years',
  category: 'financial',
  regulation: 'SEPRELAD'
})

// Privacy impact assessment
const privacyReport = generatePrivacyReport(dataProcessingActivity, {
  includeRiskAssessment: true,
  includeDataFlow: true,
  language: 'es'
})
```

## 🚨 Real-time Monitoring

Set up real-time compliance monitoring:

```tsx
import { useComplianceMonitor } from '@birhaus/compliance'

function ComplianceMonitor() {
  const {
    violations,
    alerts,
    riskScore,
    subscribe,
    unsubscribe
  } = useComplianceMonitor({
    frameworks: ['SEPRELAD', 'GDPR'],
    realTime: true,
    alertThreshold: 'medium'
  })

  useEffect(() => {
    // Subscribe to compliance events
    const unsubscribeCallback = subscribe('seprelad', (event) => {
      if (event.severity === 'high') {
        // Send immediate alert
        sendAlert('High-risk SEPRELAD violation detected')
      }
    })

    return unsubscribeCallback
  }, [subscribe])

  return (
    <div className="space-y-4">
      {/* Risk Score Display */}
      <div className="p-4 bg-white rounded-lg">
        <h3>Puntuación de Riesgo: {riskScore}/100</h3>
        <div className={`h-2 rounded ${
          riskScore > 70 ? 'bg-red-500' : 
          riskScore > 40 ? 'bg-yellow-500' : 'bg-green-500'
        }`} />
      </div>

      {/* Active Violations */}
      {violations.map(violation => (
        <div key={violation.id} className="p-4 border-l-4 border-red-500">
          <h4>{violation.title}</h4>
          <p>{violation.description}</p>
          <span>Severidad: {violation.severity}</span>
        </div>
      ))}
    </div>
  )
}
```

## 🇪🇸 Spanish-First Compliance

All compliance terminology prioritizes Spanish language:

### Regulatory Terminology

| Spanish | English | Context |
|---------|---------|---------|
| **Cumplimiento** | Compliance | General compliance |
| **Reporte Regulatorio** | Regulatory Report | Official reporting |
| **Operación Sospechosa** | Suspicious Activity | SEPRELAD reporting |
| **Consentimiento** | Consent | GDPR privacy |
| **Portabilidad de Datos** | Data Portability | User rights |
| **Derecho al Olvido** | Right to be Forgotten | Data deletion |

### Example Spanish-First Usage

```tsx
<BirhausSEPRELADDashboard
  titleEs="Panel de Cumplimiento SEPRELAD"
  titleEn="SEPRELAD Compliance Dashboard"
  
  // Spanish regulatory terms
  alerts={{
    threshold: 'Umbral de Reporte Alcanzado',
    suspicious: 'Actividad Sospechosa Detectada',
    incomplete: 'Documentación Incompleta'
  }}
  
  // Spanish report sections
  reportSections={{
    summary: 'Resumen Ejecutivo',
    transactions: 'Transacciones Reportables',
    entities: 'Entidades Involucradas',
    recommendations: 'Recomendaciones'
  }}
/>
```

## 📱 Mobile Compliance

Mobile-optimized compliance interfaces:

```tsx
<BirhausPrivacyManager
  // Mobile-first consent management
  mobileOptimized={true}
  
  // Touch-friendly controls
  touchTargets="large"
  
  // Simplified mobile UI
  mobileLayout={{
    hideSecondaryInfo: true,
    stackControls: true,
    expandableDetails: true
  }}
  
  // Mobile notifications
  pushNotifications={{
    consentUpdates: true,
    privacyRequests: true,
    dataBreaches: true
  }}
/>
```

## 🧪 Testing Compliance Components

```tsx
import { render, screen } from '@testing-library/react'
import { BirhausAuditTrail } from '@birhaus/compliance'
import { complianceTestUtils } from '@birhaus/test-utils'

describe('BirhausAuditTrail', () => {
  it('should display audit events in Spanish', () => {
    render(
      <BirhausAuditTrail
        events={mockAuditEvents}
        titleEs="Registro de Auditoría"
      />
    )
    
    expect(screen.getByText('Registro de Auditoría')).toBeInTheDocument()
  })

  it('should meet SEPRELAD compliance requirements', async () => {
    const { container } = render(
      <BirhausSEPRELADDashboard transactions={mockTransactions} />
    )
    
    const complianceResult = await complianceTestUtils.validateSEPRELAD(container)
    expect(complianceResult.isCompliant).toBe(true)
  })
})
```

## 🚀 Performance & Security

- **Bundle Size**: ~65KB gzipped (including crypto utilities)
- **Data Encryption**: AES-256-GCM for sensitive data
- **Audit Integrity**: SHA-256 hashing for tamper detection
- **Real-time Processing**: WebSocket-based compliance monitoring
- **Secure Storage**: Encrypted local storage for temporary data

## 🐛 Troubleshooting

### Common Issues

**SEPRELAD reports not generating**
```tsx
// Ensure transaction data has required fields
const transaction = {
  monto: 15000,
  moneda: 'USD', // Required for USD conversion
  documentoIdentidad: '1.234.567', // Required for reporting
  tipoDocumento: 'CI' // Required field
}
```

**GDPR consent not saving**
```tsx
// Ensure BirhausProvider is configured
<BirhausProvider 
  compliance={{
    gdpr: true,
    cookieConsent: true
  }}
>
  <App />
</BirhausProvider>
```

**Audit events not displaying**
```tsx
// Check date format for audit events
const auditEvent = {
  timestamp: new Date().toISOString(), // ISO format required
  // ... other fields
}
```

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md).

### Compliance Standards

When contributing to compliance features:

- Follow SEPRELAD documentation standards
- Implement GDPR requirements completely  
- Maintain Spanish-first language priority
- Include comprehensive audit logging
- Add proper security measures

## 📄 License

MIT © BIRHAUS Team

---

**Cumplimiento regulatorio simplificado con BIRHAUS 🏛️🇪🇸**