@tantainnovative/ndpr-toolkit/dist/lawful-basis.d.mts

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';

/**
 * Analyzes all processing activities and returns compliance gaps including
 * missing DPO approval, overdue reviews, undocumented justifications,
 * missing LIA for legitimate interests, and other documentation issues.
 *
 * @param activities Array of processing activities to analyze
 * @returns Array of identified compliance gaps
 */
export declare function assessComplianceGaps(activities: ProcessingActivity[]): LawfulBasisComplianceGap[];

/**
 * Generates a summary of all lawful basis documentation across processing activities.
 *
 * @param activities Array of processing activities to summarize
 * @returns LawfulBasisSummary with counts, breakdowns, and flagged activities
 */
export declare function generateLawfulBasisSummary(activities: ProcessingActivity[]): LawfulBasisSummary;

/**
 * Returns a human-readable description of a lawful basis with the relevant
 * NDPA section reference.
 *
 * @param basis The lawful basis to describe
 * @returns Description string including NDPA section reference
 */
export declare function getLawfulBasisDescription(basis: LawfulBasisType): string;

export declare const LawfulBasis: {
    Provider: React_2.FC<LawfulBasisProviderProps>;
    Tracker: React_2.FC<LawfulBasisTrackerProps>;
};

/**
 * Compliance gap identified across processing activities
 */
export declare interface LawfulBasisComplianceGap {
    activityId: string;
    activityName: string;
    type: 'missing_approval' | 'overdue_review' | 'missing_justification' | 'missing_lia' | 'missing_sensitive_condition' | 'missing_retention' | 'missing_data_categories' | 'missing_purposes';
    severity: 'high' | 'medium' | 'low';
    description: string;
}

declare type LawfulBasisContextValue = UseLawfulBasisReturn;

export declare const LawfulBasisProvider: React__default.FC<LawfulBasisProviderProps>;

export declare interface LawfulBasisProviderProps {
    adapter?: StorageAdapter<ProcessingActivity[]>;
    storageKey?: string;
    useLocalStorage?: boolean;
    initialActivities?: ProcessingActivity[];
    onAdd?: (activity: ProcessingActivity) => void;
    onUpdate?: (activity: ProcessingActivity) => void;
    onRemove?: (id: string) => void;
    children: React__default.ReactNode;
}

/**
 * Summary of all lawful basis documentation for compliance reporting
 */
export declare interface LawfulBasisSummary {
    /** Total number of processing activities */
    totalActivities: number;
    /** Breakdown by lawful basis */
    byBasis: Record<LawfulBasisType, number>;
    /** Number of activities involving sensitive data */
    sensitiveDataActivities: number;
    /** Number of activities involving cross-border transfers */
    crossBorderActivities: number;
    /** Activities due for review */
    activitiesDueForReview: ProcessingActivity[];
    /** Activities without DPO approval */
    activitiesWithoutApproval: ProcessingActivity[];
    /** Last updated timestamp */
    lastUpdated: number;
}

/**
 * Lawful basis tracker component. Implements NDPA Section 25 requirements for documenting
 * and tracking the lawful basis for each personal data processing activity.
 */
export declare const LawfulBasisTracker: React__default.FC<LawfulBasisTrackerProps>;

declare interface LawfulBasisTrackerClassNames {
    root?: string;
    header?: string;
    title?: 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;
    complianceScore?: string;
    gapAlert?: string;
}

declare interface LawfulBasisTrackerProps {
    /**
     * List of processing activities to display
     */
    activities: ProcessingActivity[];
    /**
     * Callback when a new activity is created.
     */
    onAdd?: (activity: Omit<ProcessingActivity, 'id' | 'createdAt' | 'updatedAt'>) => void;
    /**
     * Callback when an activity is updated.
     */
    onUpdate?: (id: string, updates: Partial<ProcessingActivity>) => void;
    /**
     * Callback when an activity is archived.
     */
    onArchive?: (id: string) => void;
    /**
     * Title displayed on the tracker
     * @default "Lawful Basis Tracker"
     */
    title?: string;
    /**
     * Description text displayed on the tracker
     * @default "Document and track the lawful basis for each processing activity as required by NDPA 2023 Section 25."
     */
    description?: string;
    /**
     * Custom CSS class for the tracker container
     */
    className?: string;
    /**
     * Custom CSS class for buttons
     */
    buttonClassName?: string;
    /**
     * Whether to show the compliance summary at the top
     * @default true
     */
    showSummary?: boolean;
    /**
     * Whether to show compliance gap alerts
     * @default true
     */
    showComplianceGaps?: boolean;
    /**
     * Override class names for individual sections of the component.
     * Takes priority over className / buttonClassName.
     */
    classNames?: LawfulBasisTrackerClassNames;
    /**
     * When true, all default styling is removed so consumers
     * can style from scratch using classNames.
     */
    unstyled?: boolean;
}

/**
 * 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)
 */
export declare type LawfulBasisType = 'consent' | 'contract' | 'legal_obligation' | 'vital_interests' | 'public_interest' | 'legitimate_interests';

/**
 * Validation result for a processing activity
 */
export declare interface LawfulBasisValidationResult {
    isValid: boolean;
    errors: string[];
    warnings: string[];
}

/**
 * Represents a Legitimate Interest Assessment (LIA)
 * Required when the lawful basis is 'legitimate_interests'
 */
export declare interface LegitimateInterestAssessment {
    /** Unique identifier */
    id: string;
    /** ID of the associated processing activity */
    processingActivityId: string;
    /** Date the assessment was conducted */
    assessmentDate: number;
    /** Person who conducted the assessment */
    assessor: {
        name: string;
        role: string;
        email: string;
    };
    /** Description of the legitimate interest being pursued */
    purposeTest: string;
    /** Why the processing is necessary for this purpose */
    necessityTest: string;
    /** Balancing test: rights of data subject vs. legitimate interest */
    balancingTest: string;
    /** Safeguards applied to protect data subject rights */
    safeguards: string[];
    /** Overall conclusion */
    conclusion: string;
    /** Whether the assessment concluded the processing is justified */
    approved: boolean;
}

/**
 * Represents a processing activity and its lawful basis
 */
export declare interface ProcessingActivity {
    /** Unique identifier */
    id: string;
    /** Name of the processing activity */
    name: string;
    /** Description of what processing is performed */
    description: string;
    /** The lawful basis for this processing activity */
    lawfulBasis: LawfulBasisType;
    /** Justification for why this lawful basis applies */
    lawfulBasisJustification: string;
    /** Categories of personal data being processed */
    dataCategories: string[];
    /** Whether sensitive personal data is involved */
    involvesSensitiveData: boolean;
    /** Condition for processing sensitive data (required if involvesSensitiveData is true) */
    sensitiveDataCondition?: SensitiveDataCondition;
    /** Categories of data subjects */
    dataSubjectCategories: string[];
    /** Purposes of the processing */
    purposes: string[];
    /** Data retention period */
    retentionPeriod: string;
    /** Justification for the retention period */
    retentionJustification?: string;
    /** Recipients or categories of recipients */
    recipients?: string[];
    /** Whether data is transferred outside Nigeria */
    crossBorderTransfer: boolean;
    /** Timestamp when the record was created */
    createdAt: number;
    /** Timestamp when the record was last updated */
    updatedAt: number;
    /** Next review date */
    reviewDate?: number;
    /** Status of the processing activity */
    status: 'active' | 'inactive' | 'under_review' | 'archived';
    /** DPO approval details */
    dpoApproval?: {
        approved: boolean;
        approvedBy: string;
        approvedAt: number;
        notes?: string;
    };
}

/**
 * Additional conditions required for processing sensitive personal data
 * per NDPA Section 30
 */
export declare type SensitiveDataCondition = 'explicit_consent' | 'employment_law' | 'vital_interests_incapable' | 'nonprofit_legitimate' | 'publicly_available' | 'legal_claims' | 'substantial_public_interest' | 'health_purposes' | 'public_health' | 'archiving_research';

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 lawful basis documentation for processing activities
 * in compliance with NDPA 2023 Section 25.
 *
 * @example
 * ```tsx
 * import { useLawfulBasis } from '@tantainnovative/ndpr-toolkit/hooks';
 *
 * function LawfulBasisRegistry() {
 *   const { activities, addActivity } = useLawfulBasis();
 *   return <p>{activities.length} processing activities documented.</p>;
 * }
 * ```
 */
export declare function useLawfulBasis({ initialActivities, adapter, storageKey, useLocalStorage, onAdd, onUpdate, onRemove, }?: UseLawfulBasisOptions): UseLawfulBasisReturn;

export declare function useLawfulBasisCompound(): LawfulBasisContextValue;

declare interface UseLawfulBasisOptions {
    /**
     * Initial processing activities to load
     */
    initialActivities?: ProcessingActivity[];
    /**
     * Pluggable storage adapter. When provided, takes precedence over storageKey/useLocalStorage.
     */
    adapter?: StorageAdapter<ProcessingActivity[]>;
    /**
     * Storage key for persisting activities
     * @default "ndpr_lawful_basis_activities"
     * @deprecated Use adapter instead
     */
    storageKey?: string;
    /**
     * Whether to use local storage to persist activities
     * @default true
     * @deprecated Use adapter instead
     */
    useLocalStorage?: boolean;
    /**
     * Callback when an activity is added
     */
    onAdd?: (activity: ProcessingActivity) => void;
    /**
     * Callback when an activity is updated
     */
    onUpdate?: (activity: ProcessingActivity) => void;
    /**
     * Callback when an activity is removed
     */
    onRemove?: (id: string) => void;
}

export declare interface UseLawfulBasisReturn {
    /**
     * All processing activities
     */
    activities: ProcessingActivity[];
    /**
     * Add a new processing activity
     */
    addActivity: (activity: Omit<ProcessingActivity, 'id' | 'createdAt' | 'updatedAt'>) => ProcessingActivity;
    /**
     * Update an existing processing activity
     */
    updateActivity: (id: string, updates: Partial<ProcessingActivity>) => ProcessingActivity | null;
    /**
     * Remove a processing activity
     */
    removeActivity: (id: string) => void;
    /**
     * Get a specific processing activity by ID
     */
    getActivity: (id: string) => ProcessingActivity | null;
    /**
     * Get a summary of all lawful basis documentation
     */
    getSummary: () => LawfulBasisSummary;
    /**
     * Validate a processing activity
     */
    validateActivity: (activity: ProcessingActivity) => LawfulBasisValidationResult;
    /**
     * Whether the adapter is still loading data (relevant for async adapters)
     */
    isLoading: boolean;
}

/**
 * Validates that all required fields are present on a processing activity
 * and that the lawful basis is properly documented.
 *
 * If lawfulBasis is 'legitimate_interests', ensures a LIA justification exists.
 * If involvesSensitiveData is true, ensures sensitiveDataCondition is set.
 *
 * @param activity The processing activity to validate
 * @returns Validation result with errors and warnings
 */
export declare function validateProcessingActivity(activity: ProcessingActivity): LawfulBasisValidationResult;

export { }