@tantainnovative/ndpr-toolkit/dist/ropa.d.ts

Nigeria Data Protection Toolkit — enterprise-grade compliance components for the Nigeria Data Protection Act (NDPA) 2023

import * as React_2 from 'react';
import React__default from 'react';

/**
 * Exports the Record of Processing Activities to a CSV string.
 * The CSV includes all key fields from each processing record.
 *
 * @param ropa - The full Record of Processing Activities
 * @returns CSV-formatted string
 */
export declare function exportROPAToCSV(ropa: RecordOfProcessingActivities): string;

/**
 * Generates a summary of the Record of Processing Activities.
 * Provides statistics and identifies records that are due for review.
 *
 * @param ropa - The full Record of Processing Activities
 * @returns Summary statistics for the ROPA
 */
export declare function generateROPASummary(ropa: RecordOfProcessingActivities): ROPASummary;

/**
 * Identifies compliance gaps in the Record of Processing Activities.
 * Finds records that are missing required information per NDPA 2023.
 *
 * @param ropa - The full Record of Processing Activities
 * @returns Array of compliance gaps grouped by record
 */
export declare function identifyComplianceGaps(ropa: RecordOfProcessingActivities): ROPAComplianceGap[];

/**
 * Lawful Basis types aligned with NDPA 2023 Part III (Sections 24-28)
 * Every processing activity must have a documented lawful basis
 */
/**
 * The six lawful bases for processing personal data per NDPA Section 25(1)
 */
declare type LawfulBasis = 'consent' | 'contract' | 'legal_obligation' | 'vital_interests' | 'public_interest' | 'legitimate_interests';

/**
 * Record of Processing Activities (ROPA) types aligned with NDPA 2023
 * Data controllers must maintain comprehensive records of all processing activities
 */

/**
 * Represents a single processing record in the ROPA
 */
export declare interface ProcessingRecord {
    /** Unique identifier */
    id: string;
    /** Name of the processing activity */
    name: string;
    /** Detailed description of the processing */
    description: string;
    /** Data controller details */
    controllerDetails: {
        name: string;
        contact: string;
        address: string;
        registrationNumber?: string;
        dpoContact?: string;
    };
    /** Joint controller details (if applicable) */
    jointControllerDetails?: {
        name: string;
        contact: string;
        address: string;
        responsibilities: string;
    };
    /** Data processor details (if processing is outsourced) */
    processorDetails?: {
        name: string;
        contact: string;
        address: string;
        contractReference?: string;
    };
    /** Lawful basis for the processing */
    lawfulBasis: LawfulBasis;
    /** Justification for the chosen lawful basis */
    lawfulBasisJustification: string;
    /** Purposes of the processing */
    purposes: string[];
    /** Categories of personal data processed */
    dataCategories: string[];
    /** Categories of sensitive personal data (if any) */
    sensitiveDataCategories?: string[];
    /** Categories of data subjects */
    dataSubjectCategories: string[];
    /** Recipients or categories of recipients */
    recipients: string[];
    /** Cross-border transfer details */
    crossBorderTransfers?: Array<{
        destinationCountry: string;
        countryCode?: string;
        safeguards: string;
        transferMechanism: string;
    }>;
    /** Data retention period */
    retentionPeriod: string;
    /** Justification for the retention period */
    retentionJustification?: string;
    /** Technical and organizational security measures */
    securityMeasures: string[];
    /** Data source (directly from data subject or from third party) */
    dataSource: 'data_subject' | 'third_party' | 'public_source' | 'other';
    /** Third-party source details (if dataSource is 'third_party') */
    thirdPartySourceDetails?: string;
    /** Whether a DPIA is required for this processing */
    dpiaRequired: boolean;
    /** Reference to the DPIA (if conducted) */
    dpiaReference?: string;
    /** Whether automated decision-making is involved */
    automatedDecisionMaking: boolean;
    /** Details of automated decision-making (if applicable) */
    automatedDecisionMakingDetails?: string;
    /** Status of the processing record */
    status: 'active' | 'inactive' | 'archived';
    /** Department or business unit responsible */
    department?: string;
    /** System or application used for processing */
    systemsUsed?: string[];
    /** Timestamp when the record was created */
    createdAt: number;
    /** Timestamp when the record was last updated */
    updatedAt: number;
    /** Timestamp when the record was last reviewed */
    lastReviewedAt?: number;
    /** Next review date */
    nextReviewDate?: number;
}

/**
 * Represents a complete Record of Processing Activities
 */
export declare interface RecordOfProcessingActivities {
    /** Unique identifier */
    id: string;
    /** Organization name */
    organizationName: string;
    /** Organization contact information */
    organizationContact: string;
    /** Organization address */
    organizationAddress: string;
    /** Data Protection Officer details */
    dpoDetails?: {
        name: string;
        email: string;
        phone?: string;
    };
    /** NDPC registration number */
    ndpcRegistrationNumber?: string;
    /** All processing records */
    records: ProcessingRecord[];
    /** Timestamp when the ROPA was last updated */
    lastUpdated: number;
    /** Version of the ROPA */
    version: string;
    /** Export format options */
    exportFormats?: ('pdf' | 'csv' | 'json' | 'xlsx')[];
}

export declare const ROPA: {
    Provider: React_2.FC<ROPAProviderProps>;
    Manager: React_2.FC<ROPAManagerProps>;
};

/**
 * Compliance gap found in a processing record
 */
export declare interface ROPAComplianceGap {
    recordId: string;
    recordName: string;
    gaps: string[];
}

declare type ROPAContextValue = UseROPAReturn;

/**
 * Record of Processing Activities (ROPA) management component. Implements the NDPA
 * accountability principle, requiring organizations to maintain comprehensive records
 * of all personal data processing activities.
 */
export declare const ROPAManager: React__default.FC<ROPAManagerProps>;

declare interface ROPAManagerClassNames {
    root?: string;
    header?: string;
    title?: string;
    orgInfo?: string;
    summary?: string;
    summaryCard?: string;
    table?: string;
    tableHeader?: string;
    tableRow?: string;
    form?: string;
    input?: string;
    select?: string;
    submitButton?: string;
    /** Alias for submitButton */
    primaryButton?: string;
    statusBadge?: string;
    exportButton?: string;
    /** Alias for exportButton */
    secondaryButton?: string;
    complianceGap?: string;
}

declare interface ROPAManagerProps {
    /**
     * The full Record of Processing Activities
     */
    ropa: RecordOfProcessingActivities;
    /**
     * Callback when a new record is added.
     */
    onAdd?: (record: ProcessingRecord) => void;
    /**
     * Callback when a record is updated.
     */
    onUpdate?: (id: string, updates: Partial<ProcessingRecord>) => void;
    /**
     * Callback when a record is archived.
     */
    onArchive?: (id: string) => void;
    /**
     * Title displayed on the manager
     * @default "Record of Processing Activities (ROPA)"
     */
    title?: string;
    /**
     * Description text
     * @default "Maintain a comprehensive record of all data processing activities as required by the NDPA accountability principle."
     */
    description?: string;
    /**
     * Custom CSS class
     */
    className?: string;
    /**
     * Custom CSS class for buttons
     */
    buttonClassName?: string;
    /**
     * Override class names for individual sections of the component.
     * Takes priority over className / buttonClassName.
     */
    classNames?: ROPAManagerClassNames;
    /**
     * When true, all default styling is removed so consumers
     * can style from scratch using classNames.
     */
    unstyled?: boolean;
}

export declare const ROPAProvider: React__default.FC<ROPAProviderProps>;

export declare interface ROPAProviderProps {
    initialData: RecordOfProcessingActivities;
    adapter?: StorageAdapter<RecordOfProcessingActivities>;
    onAdd?: (record: ProcessingRecord) => void;
    onUpdate?: (id: string, updates: Partial<ProcessingRecord>) => void;
    onArchive?: (id: string) => void;
    children: React__default.ReactNode;
}

/**
 * Summary statistics for the ROPA
 */
export declare interface ROPASummary {
    /** Total number of processing records */
    totalRecords: number;
    /** Active processing records */
    activeRecords: number;
    /** Records by lawful basis */
    byLawfulBasis: Record<LawfulBasis, number>;
    /** Records involving sensitive data */
    sensitiveDataRecords: number;
    /** Records involving cross-border transfers */
    crossBorderRecords: number;
    /** Records requiring DPIA */
    dpiaRequiredRecords: number;
    /** Records involving automated decision-making */
    automatedDecisionRecords: number;
    /** Records due for review */
    recordsDueForReview: ProcessingRecord[];
    /** Departments with most processing activities */
    topDepartments: Array<{
        department: string;
        count: number;
    }>;
    /** Last updated timestamp */
    lastUpdated: number;
}

/**
 * Validation result for a processing record
 */
export declare interface ROPAValidationResult {
    valid: boolean;
    errors: string[];
}

export declare interface StorageAdapter<T = unknown> {
    /** Load persisted data. Called once on hook mount. */
    load(): T | null | Promise<T | null>;
    /** Persist data. Called on every state change. */
    save(data: T): void | Promise<void>;
    /** Clear persisted data. Called on reset. */
    remove(): void | Promise<void>;
}

/**
 * Hook for managing a Record of Processing Activities (ROPA)
 * in compliance with NDPA 2023 requirements.
 *
 * Provides state management and utility functions for maintaining
 * a comprehensive register of all data processing activities.
 *
 * @example
 * ```tsx
 * import { useROPA } from '@tantainnovative/ndpr-toolkit/hooks';
 *
 * function ROPARegister({ initialData }) {
 *   const { ropa, addRecord, exportCSV } = useROPA({ initialData });
 *   return (
 *     <div>
 *       <p>{ropa.records.length} processing records</p>
 *       <button onClick={() => download(exportCSV())}>Export CSV</button>
 *     </div>
 *   );
 * }
 * ```
 */
export declare function useROPA({ initialData, adapter, onAdd, onUpdate, onArchive, }: UseROPAOptions): UseROPAReturn;

export declare function useROPACompound(): ROPAContextValue;

export declare interface UseROPAOptions {
    /**
     * Initial ROPA state
     */
    initialData: RecordOfProcessingActivities;
    /**
     * Pluggable storage adapter. When provided, adapter data is loaded on mount
     * and the ROPA is persisted after every mutation. Falls back to initialData
     * when no adapter data is found.
     */
    adapter?: StorageAdapter<RecordOfProcessingActivities>;
    /**
     * Callback when a record is added.
     */
    onAdd?: (record: ProcessingRecord) => void;
    /**
     * Callback when a record is updated.
     */
    onUpdate?: (id: string, updates: Partial<ProcessingRecord>) => void;
    /**
     * Callback when a record is archived.
     */
    onArchive?: (id: string) => void;
}

export declare interface UseROPAReturn {
    /**
     * Current state of the Record of Processing Activities
     */
    ropa: RecordOfProcessingActivities;
    /**
     * Add a new processing record
     */
    addRecord: (record: ProcessingRecord) => void;
    /**
     * Update an existing processing record
     */
    updateRecord: (id: string, updates: Partial<ProcessingRecord>) => void;
    /**
     * Archive a processing record by setting its status to 'archived'
     */
    archiveRecord: (id: string) => void;
    /**
     * Get a single processing record by ID
     */
    getRecord: (id: string) => ProcessingRecord | undefined;
    /**
     * Get a summary of the ROPA including statistics.
     * @deprecated Use the cached `summary` field instead — it is memoised on
     * `ropa` so consumers don't pay the recompute cost on every call.
     */
    getSummary: () => ROPASummary;
    /**
     * Export the ROPA as a CSV string.
     * @deprecated Use the cached `csv` field instead — it is memoised on
     * `ropa` so consumers don't pay the recompute cost on every call.
     */
    exportCSV: () => string;
    /**
     * Identify compliance gaps across all records.
     * @deprecated Use the cached `complianceGaps` field instead — it is
     * memoised on `ropa` so consumers don't pay the recompute cost on every call.
     */
    getComplianceGaps: () => ROPAComplianceGap[];
    /**
     * Memoised ROPA summary. Recomputed only when `ropa` changes.
     * Prefer this over `getSummary()` to avoid redundant recomputation.
     */
    summary: ROPASummary;
    /**
     * Memoised CSV export string. Recomputed only when `ropa` changes.
     * Prefer this over `exportCSV()` to avoid redundant recomputation.
     */
    csv: string;
    /**
     * Memoised compliance gap list. Recomputed only when `ropa` changes.
     * Prefer this over `getComplianceGaps()` to avoid redundant recomputation.
     */
    complianceGaps: ROPAComplianceGap[];
    /**
     * Whether the adapter is still loading data (relevant for async adapters)
     */
    isLoading: boolean;
}

/**
 * Validates a processing record to ensure all required fields are present
 * and properly filled per NDPA 2023 requirements.
 *
 * @param record - The processing record to validate
 * @returns Validation result with any errors found
 */
export declare function validateProcessingRecord(record: ProcessingRecord): ROPAValidationResult;

export { }