@tantainnovative/ndpr-toolkit 1.0.9 → 2.1.0

package/README.md

@@ -1,178 +1,349 @@
-# Nigerian Data Protection Compliance Toolkit (NDPR-Toolkit)
+# @tantainnovative/ndpr-toolkit
+
+**Compliance infrastructure for the Nigeria Data Protection Act (NDPA) 2023**
 
 [![npm version](https://img.shields.io/npm/v/@tantainnovative/ndpr-toolkit.svg)](https://www.npmjs.com/package/@tantainnovative/ndpr-toolkit)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-3178C6.svg)](https://www.typescriptlang.org/)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@tantainnovative/ndpr-toolkit)](https://bundlephobia.com/package/@tantainnovative/ndpr-toolkit)
+
+Eight production-ready modules covering consent, data subject rights, DPIA, breach notification, privacy policies, lawful basis tracking, cross-border transfers, and ROPA -- everything a data controller or processor needs under the NDPA.
+
+**[Documentation](https://ndprtoolkit.com.ng)** | **[Live Demos](https://ndprtoolkit.com.ng/ndpr-demos)** | **[npm](https://www.npmjs.com/package/@tantainnovative/ndpr-toolkit)**
 
-An open-source toolkit that helps Nigerian developers implement Nigeria Data Protection Regulation (NDPR) and Data Protection Act (DPA) compliant features in their web applications.
+---
 
-## Installation
+## Install
 
 ```bash
-npm install @tantainnovative/ndpr-toolkit
-# or
-yarn add @tantainnovative/ndpr-toolkit
-# or
 pnpm add @tantainnovative/ndpr-toolkit
 ```
 
-## Project Vision
+---
 
-This toolkit simplifies regulatory compliance for startups and businesses operating in Nigeria by providing ready-to-use components and tools for implementing data protection requirements.
+## Choose Your Import Style
 
-## Key Components
+v2.0 ships modular entry points. Pick the layer you need -- the rest stays out of your bundle.
 
-### 1. Consent Management System
+### Lightweight (zero UI dependencies)
 
-**New in v1.0.7:** Complete flexibility with headless mode, custom UI support, and event-driven architecture.
+Types, validators, and utility functions. Works in any JS/TS environment -- Node, Deno, edge functions, or the browser.
 
-#### Features:
-- **Flexible Implementation**: Use pre-built UI, headless mode, or hybrid approach
-- **Full Customization**: Override any component or behavior
-- **Event-Driven**: Subscribe to consent changes with event listeners
-- **TypeScript Support**: Fully typed with generic support for custom categories
-- **Granular Consent**: Analytics, marketing, functional, and custom categories
-- **Audit Trail**: Time-stamped consent history tracking
+```typescript
+import { validateConsent, getLawfulBasisDescription } from '@tantainnovative/ndpr-toolkit/core';
+```
 
-#### Quick Start:
+### React Hooks
 
-```tsx
-import { ConsentManager } from '@tantainnovative/ndpr-toolkit';
+Stateful hooks for every module. Requires `react` only -- no Radix, no Tailwind.
 
-// Basic usage with pre-built UI
-function App() {
-  return (
-    <ConsentManager>
-      {/* Your app content */}
-    </ConsentManager>
-  );
-}
+```typescript
+import { useConsent, useLawfulBasis } from '@tantainnovative/ndpr-toolkit/hooks';
+```
 
-// Headless mode with custom UI
-function HeadlessApp() {
-  return (
-    <ConsentManager headless>
-      <YourCustomBanner />
-      <YourCustomSettings />
-    </ConsentManager>
-  );
-}
+### Full UI Components
+
+Pre-built, styled components. Requires Tailwind CSS plus a handful of Radix primitives.
+
+```typescript
+import { ConsentBanner, LawfulBasisTracker } from '@tantainnovative/ndpr-toolkit';
 ```
 
-[See full consent management documentation](./docs/CONSENT_MANAGEMENT.md)
-
-### 2. Data Subject Rights Portal
-- Pre-built UI components for handling:
-  - Right to access personal data
-  - Right to rectification
-  - Right to erasure ("right to be forgotten")
-  - Right to restrict processing
-  - Right to data portability
-  - Dashboard for data controllers to manage requests
-  - Local storage requestService to track and update requests in demos
-
-### 3. Privacy Policy Generator
-- Interactive wizard to create NDPR-compliant privacy policies
-- Template system with customizable sections
-- Auto-update notifications when regulatory requirements change
-- Version history tracking
-
-### 4. Data Protection Impact Assessment (DPIA) Tool
-- Questionnaire-based tool to help organizations assess data processing risks
-- Risk scoring matrix
-- Mitigation recommendation engine
-- Exportable reports for compliance documentation
-
-### 5. Breach Notification Module
-- Templates for mandatory breach notifications
-- Workflow for documenting breach details
-- Timeline tracking to ensure 72-hour notification compliance
-- Notification delivery to authorities via API (if available)
-### 6. Data Subject Request Service
-- Lightweight requestService storing requests in browser localStorage for demos
-- Helper methods to update request status and retrieve history
+Install the UI peer dependencies:
+
+```bash
+pnpm add @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-label @radix-ui/react-slot lucide-react tailwind-merge clsx class-variance-authority
+```
+
+### Per-Module Imports
+
+Need just one module? Import it directly to keep your bundle minimal.
+
+```typescript
+import { ConsentBanner, useConsent } from '@tantainnovative/ndpr-toolkit/consent';
+import { BreachReportForm, useBreach } from '@tantainnovative/ndpr-toolkit/breach';
+```
+
+---
 
 ## Quick Start
 
-### Using the Toolkit in Your Project
+A consent banner in under 10 lines:
 
 ```tsx
-import { ConsentManager, useConsent } from '@tantainnovative/ndpr-toolkit';
+import { useConsent } from '@tantainnovative/ndpr-toolkit/hooks';
 
 function App() {
-  return (
-    <ConsentManager onConsentChange={(consent) => console.log('Consent updated:', consent)}>
-      <YourApp />
-    </ConsentManager>
-  );
+  const { hasConsent, acceptAll, rejectAll, shouldShowBanner } = useConsent({
+    options: [
+      { id: 'essential', label: 'Essential', description: 'Required for the site to function', required: true, purpose: 'Site operation' },
+      { id: 'analytics', label: 'Analytics', description: 'Help us improve', required: false, purpose: 'Usage analytics' },
+    ],
+  });
+
+  if (shouldShowBanner) {
+    return (
+      <div>
+        <p>We use cookies to improve your experience.</p>
+        <button onClick={acceptAll}>Accept All</button>
+        <button onClick={rejectAll}>Reject Optional</button>
+      </div>
+    );
+  }
+
+  return <main>{hasConsent('analytics') && <AnalyticsScript />}</main>;
 }
+```
 
-function YourApp() {
-  const { consentState, openSettings } = useConsent();
-  
-  return (
-    <div>
-      {consentState.analytics && <AnalyticsScript />}
-      <button onClick={openSettings}>Manage Cookies</button>
-    </div>
-  );
-}
+---
+
+## Modules
+
+### 1. Consent Management
+
+**NDPA Sections 25-26** -- Freely given, specific, informed, and unambiguous consent.
+
+```typescript
+import { ConsentBanner, ConsentManager, useConsent, validateConsent } from '@tantainnovative/ndpr-toolkit/consent';
 ```
 
-### Development
+```tsx
+<ConsentManager
+  position="bottom"
+  animation="slide"
+  onConsentChange={(consent) => {
+    if (consent.analytics) loadAnalytics();
+  }}
+>
+  <App />
+</ConsentManager>
+```
 
-To contribute or run the demo locally:
+**Key exports:** `ConsentBanner`, `ConsentManager`, `ConsentStorage`, `useConsent`, `validateConsent`, `validateConsentOptions`
 
-```bash
-# Clone the repository
-git clone https://github.com/tantainnovative/ndpr-toolkit.git
-cd ndpr-toolkit
+---
+
+### 2. Data Subject Rights (DSR)
 
-# Install dependencies
-pnpm install
+**NDPA Part IV, Sections 29-36** -- All 8 rights: information, access, rectification, erasure, restriction, portability, objection, and automated decision-making.
 
-# Run development server
-pnpm dev
+```typescript
+import { DSRRequestForm, DSRDashboard, useDSR, formatDSRRequest } from '@tantainnovative/ndpr-toolkit/dsr';
 ```
 
-Open [http://localhost:3000](http://localhost:3000) to see the demo.
+```tsx
+const { submitRequest, requests } = useDSR({
+  requestTypes: [
+    { id: 'access', name: 'Access Request', description: 'Right of access (Section 30)', estimatedCompletionTime: 30, requiresAdditionalInfo: false },
+  ],
+});
+```
 
-## Deployment
+**Key exports:** `DSRRequestForm`, `DSRDashboard`, `DSRTracker`, `useDSR`, `formatDSRRequest`
 
-### GitHub Pages
+---
 
-This project is configured to deploy automatically to GitHub Pages using GitHub Actions. When you push changes to the `main` branch, the following will happen:
+### 3. Data Protection Impact Assessment (DPIA)
 
-1. The GitHub Actions workflow will build the project
-2. The built files will be deployed to GitHub Pages
-3. Your site will be available at `https://[your-username].github.io/ndpr-toolkit/`
+**NDPA Section 38-39** -- Mandatory risk assessment for high-risk processing activities.
 
-To manually deploy to GitHub Pages:
+```typescript
+import { DPIAQuestionnaire, DPIAReport, useDPIA, assessDPIARisk } from '@tantainnovative/ndpr-toolkit/dpia';
+```
 
-```bash
-# Build the project
-npm run build
+```tsx
+const { currentSection, answers, goToNextSection, getResult } = useDPIA({
+  sections: dpiaSections,
+  onComplete: (result) => saveAssessment(result),
+});
+```
+
+**Key exports:** `DPIAQuestionnaire`, `DPIAReport`, `StepIndicator`, `useDPIA`, `assessDPIARisk`
+
+---
 
-# Deploy to GitHub Pages (if you have gh-pages installed)
-npm run deploy
+### 4. Breach Notification
+
+**NDPA Section 40** -- 72-hour notification to the NDPC, plus data subject notification.
+
+```typescript
+import { BreachReportForm, BreachNotificationManager, useBreach, calculateBreachSeverity } from '@tantainnovative/ndpr-toolkit/breach';
+```
+
+```tsx
+const { createReport, reports, assessRisk } = useBreach({
+  categories: breachCategories,
+  onReport: (report) => notifyNDPC(report),
+});
 ```
 
-#### Configuration
+**Key exports:** `BreachReportForm`, `BreachRiskAssessment`, `BreachNotificationManager`, `RegulatoryReportGenerator`, `useBreach`, `calculateBreachSeverity`
 
-The GitHub Pages deployment is configured in the following files:
-- `next.config.ts` - Contains the Next.js configuration for static export
-- `.github/workflows/deploy.yml` - Contains the GitHub Actions workflow for automated deployment
+---
 
-## Technical Stack
+### 5. Privacy Policy Generator
 
-- Next.js with App Router
-- TypeScript
-- Tailwind CSS
-- React
+**NDPA Sections 27-28** -- Multi-step wizard producing NDPA-compliant privacy policies with PDF/DOCX export.
+
+```typescript
+import { PolicyGenerator, PolicyPreview, usePrivacyPolicy, generatePolicyText } from '@tantainnovative/ndpr-toolkit/policy';
+```
+
+```tsx
+<PolicyGenerator />
+```
+
+The wizard covers organization info, data collection practices, data sharing, custom sections, and a preview with export.
+
+**Key exports:** `PolicyGenerator`, `PolicyPreview`, `PolicyExporter`, `usePrivacyPolicy`, `generatePolicyText`
+
+---
+
+### 6. Lawful Basis Tracker
+
+**NDPA Section 25** -- Document and manage the lawful basis for every processing activity. Covers all six bases: consent, contract, legal obligation, vital interests, public interest, and legitimate interests.
+
+```typescript
+import { LawfulBasisTracker, useLawfulBasis, validateProcessingActivity, getLawfulBasisDescription } from '@tantainnovative/ndpr-toolkit/lawful-basis';
+```
+
+```tsx
+const { activities, addActivity, getSummary } = useLawfulBasis();
+
+addActivity({
+  name: 'Email marketing',
+  description: 'Send promotional emails',
+  lawfulBasis: 'consent',
+  lawfulBasisJustification: 'Explicit opt-in at signup',
+  dataCategories: ['email', 'name'],
+  involvesSensitiveData: false,
+  dataSubjectCategories: ['customers'],
+  purposes: ['marketing'],
+  retentionPeriod: '2 years',
+  crossBorderTransfer: false,
+  status: 'active',
+});
+```
+
+**Key exports:** `LawfulBasisTracker`, `useLawfulBasis`, `validateProcessingActivity`, `getLawfulBasisDescription`, `assessComplianceGaps`, `generateLawfulBasisSummary`
+
+---
+
+### 7. Cross-Border Transfer Assessment
+
+**NDPA Part VI, Sections 41-45** -- Evaluate adequacy decisions, standard contractual clauses, binding corporate rules, and derogations for international data transfers.
+
+```typescript
+import { CrossBorderTransferManager, useCrossBorderTransfer, validateTransfer, assessTransferRisk } from '@tantainnovative/ndpr-toolkit/cross-border';
+```
+
+```tsx
+const { transfers, addTransfer, getSummary } = useCrossBorderTransfer({
+  onAdd: (transfer) => logTransfer(transfer),
+});
+```
+
+**Key exports:** `CrossBorderTransferManager`, `useCrossBorderTransfer`, `validateTransfer`, `getTransferMechanismDescription`, `assessTransferRisk`, `isNDPCApprovalRequired`
+
+---
+
+### 8. Record of Processing Activities (ROPA)
+
+**NDPC Regulatory Guidance** -- Maintain comprehensive records of all processing activities for audit readiness.
+
+```typescript
+import { ROPAManager, useROPA, generateROPASummary, exportROPAToCSV } from '@tantainnovative/ndpr-toolkit/ropa';
+```
+
+```tsx
+const { ropa, addRecord, getSummary } = useROPA({
+  initialData: { id: 'ropa-1', organizationName: 'Acme Ltd', organizationContact: 'dpo@acme.ng', organizationAddress: 'Lagos, Nigeria', records: [], lastUpdated: Date.now(), version: '1.0' },
+});
+```
+
+**Key exports:** `ROPAManager`, `useROPA`, `validateProcessingRecord`, `generateROPASummary`, `exportROPAToCSV`, `identifyComplianceGaps`
+
+---
+
+## Available Import Paths
+
+| Path | What you get | Dependencies |
+|------|-------------|--------------|
+| `/core` | Types + utility functions | `tslib`, `uuid` |
+| `/hooks` | React hooks for all 8 modules | `react` |
+| `/consent` | Consent components + hook + utils | `react`, Radix, Tailwind |
+| `/dsr` | DSR components + hook + utils | `react`, Radix, Tailwind |
+| `/dpia` | DPIA components + hook + utils | `react`, Radix, Tailwind |
+| `/breach` | Breach components + hook + utils | `react`, Radix, Tailwind |
+| `/policy` | Policy components + hook + utils | `react`, Radix, Tailwind, `jspdf` |
+| `/lawful-basis` | Lawful basis component + hook + utils | `react`, Radix, Tailwind |
+| `/cross-border` | Cross-border component + hook + utils | `react`, Radix, Tailwind |
+| `/ropa` | ROPA component + hook + utils | `react`, Radix, Tailwind |
+| `/unstyled` | Unstyled consent primitives | `react` |
+| `.` (default) | Everything | All peer deps |
+
+---
+
+## NDPA 2023 Overview
+
+The **Nigeria Data Protection Act (NDPA) 2023** replaced the NDPR 2019 and established the **Nigeria Data Protection Commission (NDPC)** as the independent regulatory body.
+
+| Aspect | NDPR (2019) | NDPA (2023) |
+|--------|-------------|-------------|
+| Legal status | NITDA regulation | Act of the National Assembly |
+| Regulator | NITDA | NDPC (independent commission) |
+| Scope | Organizations processing data in Nigeria | Broader territorial + extraterritorial application |
+| Enforcement | Limited | Independent investigation and penalty powers |
+| Data subject rights | 6 rights | 8 rights (added information + automated decision-making) |
+| Cross-border transfers | Basic provisions | Comprehensive framework with adequacy decisions |
+| Breach notification | 72 hours to NITDA | 72 hours to NDPC (Section 40) |
+| DPIA | Recommended | Required for high-risk processing (Section 38) |
+
+---
+
+## TypeScript
+
+The toolkit is written in TypeScript and exports all types:
+
+```typescript
+import type {
+  // Consent
+  ConsentOption, ConsentSettings, LawfulBasisType,
+  // DSR
+  DSRRequest, DSRType, DSRStatus, RequestType,
+  // DPIA
+  DPIAQuestion, DPIASection, DPIAResult, DPIARisk,
+  // Breach
+  BreachReport, BreachCategory, RiskAssessment,
+  // Policy
+  PolicySection, PolicyTemplate, OrganizationInfo, PrivacyPolicy,
+  // Lawful Basis
+  LawfulBasis, ProcessingActivity, LawfulBasisSummary,
+  // Cross-Border
+  CrossBorderTransfer, TransferMechanism, AdequacyStatus,
+  // ROPA
+  ProcessingRecord, RecordOfProcessingActivities, ROPASummary,
+} from '@tantainnovative/ndpr-toolkit/core';
+```
+
+---
+
+## Contributing
+
+Contributions are welcome. Please read the [Contributing Guide](./CONTRIBUTING.md) before submitting a pull request.
+
+---
 
 ## License
 
-MIT License
+MIT
+
+---
+
+## Author
 
-## Developed by
+**Abraham Esandayinze Tanta** — Software Engineer & Data Protection Compliance Specialist
 
-Tanta Innovative - Positioning as a thought leader in regulatory tech solutions for Nigeria
+- GitHub: [@mr-tanta](https://github.com/mr-tanta)
+- LinkedIn: [mr-tanta](https://linkedin.com/in/mr-tanta)
+- Organization: [Tanta Innovative](https://github.com/tantainnovative)

package/dist/breach-BpSBPrdk.d.mts

@@ -0,0 +1,185 @@
+/**
+ * Breach notification types aligned with NDPA 2023 Section 40
+ * Data controllers must notify the NDPC within 72 hours of becoming aware of a breach
+ * Data subjects must be notified without undue delay when breach is likely to result in high risk
+ */
+/**
+ * Represents a data breach category
+ */
+interface BreachCategory {
+    /** Unique identifier for the category */
+    id: string;
+    /** Display name for the category */
+    name: string;
+    /** Description of this breach category */
+    description: string;
+    /** Default severity level for this category */
+    defaultSeverity: 'low' | 'medium' | 'high' | 'critical';
+}
+/**
+ * Represents a data breach report
+ */
+interface BreachReport {
+    /** Unique identifier for the breach report */
+    id: string;
+    /** Title/summary of the breach */
+    title: string;
+    /** Detailed description of the breach */
+    description: string;
+    /** Category of the breach */
+    category: string;
+    /** Timestamp when the breach was discovered */
+    discoveredAt: number;
+    /** Timestamp when the breach occurred (if known) */
+    occurredAt?: number;
+    /** Timestamp when the breach was reported internally */
+    reportedAt: number;
+    /** Person who reported the breach */
+    reporter: {
+        name: string;
+        email: string;
+        department: string;
+        phone?: string;
+    };
+    /** Systems or data affected by the breach */
+    affectedSystems: string[];
+    /** Types of data involved in the breach */
+    dataTypes: string[];
+    /** Whether sensitive personal data is involved (NDPA Section 30) */
+    involvesSensitiveData?: boolean;
+    /** Estimated number of data subjects affected */
+    estimatedAffectedSubjects?: number;
+    /** Whether the breach is ongoing or contained */
+    status: 'ongoing' | 'contained' | 'resolved';
+    /** Initial actions taken to address the breach */
+    initialActions?: string;
+    /** Attachments related to the breach */
+    attachments?: Array<{
+        id: string;
+        name: string;
+        type: string;
+        url: string;
+        addedAt: number;
+    }>;
+}
+/**
+ * Represents a risk assessment for a data breach
+ */
+interface RiskAssessment {
+    /** Unique identifier for the risk assessment */
+    id: string;
+    /** ID of the breach this assessment is for */
+    breachId: string;
+    /** Timestamp when the assessment was conducted */
+    assessedAt: number;
+    /** Person who conducted the assessment */
+    assessor: {
+        name: string;
+        role: string;
+        email: string;
+    };
+    /** Confidentiality impact (1-5) */
+    confidentialityImpact: number;
+    /** Integrity impact (1-5) */
+    integrityImpact: number;
+    /** Availability impact (1-5) */
+    availabilityImpact: number;
+    /** Likelihood of harm to data subjects (1-5) */
+    harmLikelihood: number;
+    /** Severity of potential harm to data subjects (1-5) */
+    harmSeverity: number;
+    /** Overall risk score */
+    overallRiskScore: number;
+    /** Risk level based on the overall score */
+    riskLevel: 'low' | 'medium' | 'high' | 'critical';
+    /** Whether the breach is likely to result in a risk to rights and freedoms */
+    risksToRightsAndFreedoms: boolean;
+    /** Whether the breach is likely to result in a high risk to rights and freedoms */
+    highRisksToRightsAndFreedoms: boolean;
+    /** Justification for the risk assessment */
+    justification: string;
+}
+/**
+ * Represents notification requirements for a data breach per NDPA Section 40
+ */
+interface NotificationRequirement {
+    /**
+     * Whether NDPC notification is required
+     * Per NDPA Section 40, notification to NDPC is required for all breaches
+     * that pose a risk to data subjects' rights and freedoms
+     */
+    ndpcNotificationRequired: boolean;
+    /**
+     * Deadline for NDPC notification (72 hours from discovery)
+     * NDPA Section 40(1)
+     */
+    ndpcNotificationDeadline: number;
+    /**
+     * Whether data subject notification is required
+     * Per NDPA Section 40(4), required when breach is likely to result in
+     * high risk to rights and freedoms of data subjects
+     */
+    dataSubjectNotificationRequired: boolean;
+    /** Justification for the notification decision */
+    justification: string;
+    /**
+     * @deprecated Use ndpcNotificationRequired instead. Kept for backward compatibility.
+     */
+    nitdaNotificationRequired?: boolean;
+    /**
+     * @deprecated Use ndpcNotificationDeadline instead. Kept for backward compatibility.
+     */
+    nitdaNotificationDeadline?: number;
+}
+/**
+ * Represents a notification sent to the NDPC (Nigeria Data Protection Commission)
+ */
+interface RegulatoryNotification {
+    /** Unique identifier for the notification */
+    id: string;
+    /** ID of the breach this notification is for */
+    breachId: string;
+    /** Timestamp when the notification was sent */
+    sentAt: number;
+    /** Method used to send the notification */
+    method: 'email' | 'portal' | 'letter' | 'other';
+    /** Reference number assigned by the NDPC (if available) */
+    referenceNumber?: string;
+    /** Contact person at the NDPC */
+    ndpcContact?: {
+        name: string;
+        email: string;
+        phone?: string;
+    };
+    /** Content of the notification */
+    content: string;
+    /** Attachments included with the notification */
+    attachments?: Array<{
+        id: string;
+        name: string;
+        type: string;
+        url: string;
+    }>;
+    /** Follow-up communications with the NDPC */
+    followUps?: Array<{
+        timestamp: number;
+        direction: 'sent' | 'received';
+        content: string;
+        attachments?: Array<{
+            id: string;
+            name: string;
+            type: string;
+            url: string;
+        }>;
+    }>;
+    /**
+     * @deprecated Use ndpcContact instead. Kept for backward compatibility.
+     */
+    nitdaContact?: {
+        name: string;
+        email: string;
+        phone?: string;
+    };
+}
+
+export type { BreachReport as B, NotificationRequirement as N, RiskAssessment as R, BreachCategory as a, RegulatoryNotification as b };