breakpilot-compliance/consent-sdk/README.md

# @breakpilot/consent-sdk

DSGVO/TTDSG-konformes Consent Management SDK fuer Web, PWA und Mobile Apps.

## Features

- DSGVO, TTDSG und ePrivacy-Richtlinie konform
- IAB TCF 2.2 Unterstuetzung
- Google Consent Mode v2 Integration
- Plattformuebergreifend (Web, PWA, iOS, Android, Flutter, React Native)
- Typsicher (TypeScript)
- Barrierefreundlich (WCAG 2.1 AA)
- Open Source (Apache 2.0)

## Installation

```bash
npm install @breakpilot/consent-sdk
```

## Quick Start

### Vanilla JavaScript

```javascript
import { ConsentManager } from '@breakpilot/consent-sdk';

const consent = new ConsentManager({
  apiEndpoint: 'https://consent.example.com/api/v1',
  siteId: 'site_abc123',
  language: 'de',
});

await consent.init();

// Consent pruefen
if (consent.hasConsent('analytics')) {
  // Analytics laden
}

// Events
consent.on('change', (newConsent) => {
  console.log('Consent changed:', newConsent);
});
```

### React

```tsx
import { ConsentProvider, useConsent, ConsentBanner, ConsentGate } from '@breakpilot/consent-sdk/react';

const config = {
  apiEndpoint: 'https://consent.example.com/api/v1',
  siteId: 'site_abc123',
};

function App() {
  return (
    <ConsentProvider config={config}>
      <ConsentBanner />
      <MainContent />
    </ConsentProvider>
  );
}

function AnalyticsSection() {
  return (
    <ConsentGate
      category="analytics"
      placeholder={<p>Analytics erfordert Ihre Zustimmung.</p>}
    >
      <GoogleAnalytics />
    </ConsentGate>
  );
}

function SettingsButton() {
  const { showSettings } = useConsent();
  return <button onClick={showSettings}>Cookie-Einstellungen</button>;
}
```

## Script Blocking

Verwenden Sie `data-consent` um Skripte zu blockieren:

```html
<!-- Externes Script -->
<script
  data-consent="analytics"
  data-src="https://www.googletagmanager.com/gtag/js?id=GA-XXXXX"
  type="text/plain">
</script>

<!-- Inline Script -->
<script data-consent="marketing" type="text/plain">
  fbq('init', 'XXXXX');
</script>

<!-- iFrame -->
<iframe
  data-consent="social"
  data-src="https://www.youtube.com/embed/XXXXX"
  title="YouTube Video">
</iframe>
```

## Consent-Kategorien

| Kategorie | Beschreibung | Einwilligung |
|-----------|--------------|--------------|
| `essential` | Technisch notwendig | Nicht erforderlich |
| `functional` | Personalisierung | Erforderlich |
| `analytics` | Nutzungsanalyse | Erforderlich |
| `marketing` | Werbung | Erforderlich |
| `social` | Social Media | Erforderlich |

## Konfiguration

```typescript
const config: ConsentConfig = {
  // Pflicht
  apiEndpoint: 'https://consent.example.com/api/v1',
  siteId: 'site_abc123',

  // Sprache
  language: 'de',
  fallbackLanguage: 'en',

  // UI
  ui: {
    position: 'bottom',      // 'bottom' | 'top' | 'center'
    layout: 'modal',         // 'bar' | 'modal' | 'floating'
    theme: 'auto',           // 'light' | 'dark' | 'auto'
    zIndex: 999999,
  },

  // Verhalten
  consent: {
    required: true,
    rejectAllVisible: true,  // "Alle ablehnen" Button
    acceptAllVisible: true,  // "Alle akzeptieren" Button
    granularControl: true,   // Kategorien einzeln waehlbar
    rememberDays: 365,       // Speicherdauer
    recheckAfterDays: 180,   // Erneut fragen nach X Tagen
  },

  // Callbacks
  onConsentChange: (consent) => {
    console.log('Consent:', consent);
  },

  // Debug
  debug: process.env.NODE_ENV === 'development',
};
```

## API

### ConsentManager

```typescript
// Initialisieren
await consent.init();

// Consent pruefen
consent.hasConsent('analytics');        // boolean
consent.hasVendorConsent('google');     // boolean

// Consent abrufen
consent.getConsent();                   // ConsentState | null

// Consent setzen
await consent.setConsent({
  essential: true,
  analytics: true,
  marketing: false,
});

// Aktionen
await consent.acceptAll();
await consent.rejectAll();
await consent.revokeAll();

// Banner
consent.showBanner();
consent.hideBanner();
consent.showSettings();
consent.needsConsent();                 // boolean

// Events
consent.on('change', callback);
consent.on('banner_show', callback);
consent.on('banner_hide', callback);
consent.off('change', callback);

// Export (DSGVO Art. 20)
const data = await consent.exportConsent();
```

### React Hooks

```typescript
// Basis-Hook
const {
  consent,
  isLoading,
  isBannerVisible,
  needsConsent,
  hasConsent,
  acceptAll,
  rejectAll,
  showBanner,
  showSettings,
} = useConsent();

// Mit Kategorie
const { allowed } = useConsent('analytics');

// Manager-Zugriff
const manager = useConsentManager();
```

## Rechtliche Compliance

Dieses SDK erfuellt:

- **DSGVO** (EU 2016/679) - Art. 4, 6, 7, 12, 13, 17, 20
- **TTDSG** (Deutschland) - § 25
- **ePrivacy-Richtlinie** (2002/58/EG) - Art. 5
- **Planet49-Urteil** (EuGH C-673/17)
- **BGH Cookie-Einwilligung II** (2023)
- **DSK Orientierungshilfe Telemedien**

## Lizenz

Apache 2.0 - Open Source, kommerziell nutzbar.

```
Copyright 2026 BreakPilot GmbH

Licensed under the Apache License, Version 2.0
```