Package Exports

@birhaus/compliance
@birhaus/compliance/dist/index.js
@birhaus/compliance/dist/index.mjs

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@birhaus/compliance) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@birhaus/compliance

Regulatory compliance and audit trail components for BIRHAUS design system

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

npm install @birhaus/compliance

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

🎯 Quick Start

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:

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

// 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:

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:

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
      }}
    />
  )
}

✅ 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:

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:

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:

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:

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

<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:

<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

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

// 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

// Ensure BirhausProvider is configured
<BirhausProvider 
  compliance={{
    gdpr: true,
    cookieConsent: true
  }}
>
  <App />
</BirhausProvider>

Audit events not displaying

// 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.

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

Cumplimiento regulatorio simplificado con BIRHAUS 🏛️🇪🇸