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

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

import { RefObject } from 'react';

/**
 * Adequacy status of a destination country
 */
declare type AdequacyStatus = 'adequate' | 'inadequate' | 'pending_review' | 'unknown';

/**
 * 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
 */
declare 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';
}

declare type BreachCompositeState = {
    reports: BreachReport[];
    assessments: RiskAssessment[];
    notifications: RegulatoryNotification_2[];
};

export declare interface BreachNotificationAssessment {
    /** Whether all applicable mandated content items are satisfied. */
    complete: boolean;
    /** Completeness of applicable content items, 0–100. */
    completeness: number;
    /** GAID 2025 Article 33(5) / NDPA S. 40(2) content of the notification to the Commission. */
    notificationToCommission: BreachNotificationItem[];
    /** NDPA S. 40(3) communication to data subjects — populated only when high-risk. */
    dataSubjectCommunication: BreachNotificationItem[];
    /** Whether a data-subject communication is owed (high risk). */
    dataSubjectCommunicationRequired: boolean;
    timing: BreachNotificationTiming;
    /** Labels of unsatisfied applicable items. */
    missing: string[];
    /** Actionable next steps, including timing warnings. */
    recommendations: string[];
    asOf: number;
}

declare interface BreachNotificationAssessment_2 {
    /** Whether all applicable mandated content items are satisfied. */
    complete: boolean;
    /** Completeness of applicable content items, 0–100. */
    completeness: number;
    /** GAID 2025 Article 33(5) / NDPA S. 40(2) content of the notification to the Commission. */
    notificationToCommission: BreachNotificationItem_2[];
    /** NDPA S. 40(3) communication to data subjects — populated only when high-risk. */
    dataSubjectCommunication: BreachNotificationItem_2[];
    /** Whether a data-subject communication is owed (high risk). */
    dataSubjectCommunicationRequired: boolean;
    timing: BreachNotificationTiming_2;
    /** Labels of unsatisfied applicable items. */
    missing: string[];
    /** Actionable next steps, including timing warnings. */
    recommendations: string[];
    asOf: number;
}

export declare interface BreachNotificationItem {
    /** Stable identifier for the requirement. */
    id: string;
    /** Human-readable requirement. */
    label: string;
    /** Authoritative citation, e.g. `GAID 2025 Art. 33(5)(a)`. */
    section: string;
    /** Whether the report satisfies it. */
    satisfied: boolean;
}

declare interface BreachNotificationItem_2 {
    /** Stable identifier for the requirement. */
    id: string;
    /** Human-readable requirement. */
    label: string;
    /** Authoritative citation, e.g. `GAID 2025 Art. 33(5)(a)`. */
    section: string;
    /** Whether the report satisfies it. */
    satisfied: boolean;
}

/**
 * Personal-data-breach notification completeness checker for NDPA 2023
 * Section 40, as detailed by NDPC General Application and Implementation
 * Directive (GAID) 2025 Article 33.
 *
 * Section 40(2) requires a data controller to notify the Commission within 72
 * hours of becoming aware of a breach likely to result in a risk to data
 * subjects' rights and freedoms. GAID 2025 Article 33(5)(a)–(h) enumerates the
 * content that a notification to the Commission "shall include". Where the
 * breach is likely to result in a *high* risk, Section 40(3) additionally
 * requires the controller to communicate the breach to affected data subjects
 * in plain and clear language.
 *
 * This assesses a `BreachReport` against those requirements: which mandated
 * content items are present, whether the 72-hour window is met, and whether a
 * data-subject communication is owed. It is a documentation-completeness aid,
 * not legal advice — verify against current NDPC guidance.
 *
 * @see NDPA 2023 Section 40 (Personal data breaches)
 * @see NDPC GAID 2025 Article 33 (Data Breach Notification)
 */

export declare interface BreachNotificationOptions {
    /** Risk assessment for the breach; drives whether data-subject communication is required. */
    assessment?: RiskAssessment;
    /** The regulatory notification actually sent, if any — used to judge timeliness. */
    notification?: RegulatoryNotification_2;
    /** Reference "now" in epoch ms. Defaults to `Date.now()`. */
    asOf?: number;
    /** Notification window in hours. Defaults to 72 (NDPA S. 40(2)). */
    deadlineHours?: number;
    /**
     * Explicit high-risk flag (NDPA S. 40(3)). When omitted, derived from
     * `assessment.highRisksToRightsAndFreedoms`.
     */
    highRisk?: boolean;
}

/**
 * Personal-data-breach notification completeness checker for NDPA 2023
 * Section 40, as detailed by NDPC General Application and Implementation
 * Directive (GAID) 2025 Article 33.
 *
 * Section 40(2) requires a data controller to notify the Commission within 72
 * hours of becoming aware of a breach likely to result in a risk to data
 * subjects' rights and freedoms. GAID 2025 Article 33(5)(a)–(h) enumerates the
 * content that a notification to the Commission "shall include". Where the
 * breach is likely to result in a *high* risk, Section 40(3) additionally
 * requires the controller to communicate the breach to affected data subjects
 * in plain and clear language.
 *
 * This assesses a `BreachReport` against those requirements: which mandated
 * content items are present, whether the 72-hour window is met, and whether a
 * data-subject communication is owed. It is a documentation-completeness aid,
 * not legal advice — verify against current NDPC guidance.
 *
 * @see NDPA 2023 Section 40 (Personal data breaches)
 * @see NDPC GAID 2025 Article 33 (Data Breach Notification)
 */

declare interface BreachNotificationOptions_2 {
    /** Risk assessment for the breach; drives whether data-subject communication is required. */
    assessment?: RiskAssessment_2;
    /** The regulatory notification actually sent, if any — used to judge timeliness. */
    notification?: RegulatoryNotification;
    /** Reference "now" in epoch ms. Defaults to `Date.now()`. */
    asOf?: number;
    /** Notification window in hours. Defaults to 72 (NDPA S. 40(2)). */
    deadlineHours?: number;
    /**
     * Explicit high-risk flag (NDPA S. 40(3)). When omitted, derived from
     * `assessment.highRisksToRightsAndFreedoms`.
     */
    highRisk?: boolean;
}

export declare interface BreachNotificationTiming {
    /** `discoveredAt` + the notification window. */
    deadline: number;
    /** Whole hours between discovery and `asOf`. */
    hoursSinceDiscovery: number;
    /** Whether a regulatory notification has been recorded. */
    notified: boolean;
    /** When the regulatory notification was sent, if any. */
    notifiedAt?: number;
    /** Whether the notification (or, if none, `asOf`) falls within the deadline. */
    withinDeadline: boolean;
    /** Whole hours from `asOf` to the deadline (negative once past). */
    hoursRemaining: number;
    /** Whether the deadline has been missed. */
    overdue: boolean;
    /** Late filings must state the reasons for the delay (NDPA S. 40(2)). */
    requiresDelayJustification: boolean;
}

declare interface BreachNotificationTiming_2 {
    /** `discoveredAt` + the notification window. */
    deadline: number;
    /** Whole hours between discovery and `asOf`. */
    hoursSinceDiscovery: number;
    /** Whether a regulatory notification has been recorded. */
    notified: boolean;
    /** When the regulatory notification was sent, if any. */
    notifiedAt?: number;
    /** Whether the notification (or, if none, `asOf`) falls within the deadline. */
    withinDeadline: boolean;
    /** Whole hours from `asOf` to the deadline (negative once past). */
    hoursRemaining: number;
    /** Whether the deadline has been missed. */
    overdue: boolean;
    /** Late filings must state the reasons for the delay (NDPA S. 40(2)). */
    requiresDelayJustification: boolean;
}

/**
 * Represents a data breach report
 */
export declare 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;
    /**
     * Approximate number of personal data RECORDS concerned (distinct from subject count).
     * Required content under NDPA Section 40(1)(a) and Section 40(2).
     */
    approximateRecordCount?: number;
    /**
     * Categories of data subjects affected (e.g. customers, employees, minors, patients).
     * Required content under NDPA Section 40(1)(a) and Section 40(2).
     */
    dataSubjectCategories?: string[];
    /**
     * Likely consequences of the breach for affected data subjects (e.g. identity theft,
     * financial loss, reputational damage). Reported to the NDPC and, where applicable,
     * communicated to data subjects under Section 40(3).
     */
    likelyConsequences?: string;
    /**
     * Measures taken or proposed to mitigate adverse effects of the breach.
     * Required content for Section 40(3) communications to data subjects.
     */
    mitigationMeasures?: string;
    /**
     * Whether this is a phased / interim report submitted before full investigation
     * is complete. The NDPC permits phased reporting where complete information is
     * not available within 72 hours.
     */
    isPhasedReport?: boolean;
    /**
     * ID of the prior phased report this report supplements, if any.
     */
    supplementsReportId?: string;
    /**
     * Data Protection Officer contact details. The DPO is the named contact point
     * for the NDPC per NDPA Section 32(3)(c). Required content in the regulatory
     * report (Section 40(2)).
     */
    dpoContact?: {
        name: string;
        email: string;
        phone?: string;
    };
    /** 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 data breach report
 */
declare interface BreachReport_2 {
    /** 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;
    /**
     * Approximate number of personal data RECORDS concerned (distinct from subject count).
     * Required content under NDPA Section 40(1)(a) and Section 40(2).
     */
    approximateRecordCount?: number;
    /**
     * Categories of data subjects affected (e.g. customers, employees, minors, patients).
     * Required content under NDPA Section 40(1)(a) and Section 40(2).
     */
    dataSubjectCategories?: string[];
    /**
     * Likely consequences of the breach for affected data subjects (e.g. identity theft,
     * financial loss, reputational damage). Reported to the NDPC and, where applicable,
     * communicated to data subjects under Section 40(3).
     */
    likelyConsequences?: string;
    /**
     * Measures taken or proposed to mitigate adverse effects of the breach.
     * Required content for Section 40(3) communications to data subjects.
     */
    mitigationMeasures?: string;
    /**
     * Whether this is a phased / interim report submitted before full investigation
     * is complete. The NDPC permits phased reporting where complete information is
     * not available within 72 hours.
     */
    isPhasedReport?: boolean;
    /**
     * ID of the prior phased report this report supplements, if any.
     */
    supplementsReportId?: string;
    /**
     * Data Protection Officer contact details. The DPO is the named contact point
     * for the NDPC per NDPA Section 32(3)(c). Required content in the regulatory
     * report (Section 40(2)).
     */
    dpoContact?: {
        name: string;
        email: string;
        phone?: string;
    };
    /** 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;
    }>;
}

/**
 * Compliance Audit Returns (CAR) scheduling under the NDPC General Application
 * and Implementation Directive (GAID) 2025.
 *
 * A Data Controller/Processor of Major Importance (DCPMI) must conduct an
 * initial compliance audit within 15 months of commencing data processing, and
 * thereafter file a Compliance Audit Return with the NDPC annually (default
 * deadline 31 March, filed through the NDPC Information Management Portal/NIMP).
 *
 * This computes the schedule (initial-audit due date, the next annual filing
 * deadline relative to a reference date) and a light status. NDPC deadlines
 * shift (the 2026 filing was extended to 30 May), so the annual deadline is
 * configurable and per-year overrides are supported. The audit *content* itself
 * is the organisation's compliance posture — pair this with `getComplianceScore`.
 *
 * @see NDPC General Application and Implementation Directive (GAID) 2025
 */

export declare interface CARInput {
    /** ISO date (YYYY-MM-DD) the organisation commenced data processing. */
    commencementDate: string;
    /** Reference date to evaluate against (YYYY-MM-DD). Defaults to today. */
    asOf?: string;
    /** DCPMI tier; CAR applies to DCPMIs only. Omit to assume applicable. */
    tier?: DCPMITier_2;
}

/**
 * Compliance Audit Returns (CAR) scheduling under the NDPC General Application
 * and Implementation Directive (GAID) 2025.
 *
 * A Data Controller/Processor of Major Importance (DCPMI) must conduct an
 * initial compliance audit within 15 months of commencing data processing, and
 * thereafter file a Compliance Audit Return with the NDPC annually (default
 * deadline 31 March, filed through the NDPC Information Management Portal/NIMP).
 *
 * This computes the schedule (initial-audit due date, the next annual filing
 * deadline relative to a reference date) and a light status. NDPC deadlines
 * shift (the 2026 filing was extended to 30 May), so the annual deadline is
 * configurable and per-year overrides are supported. The audit *content* itself
 * is the organisation's compliance posture — pair this with `getComplianceScore`.
 *
 * @see NDPC General Application and Implementation Directive (GAID) 2025
 */

declare interface CARInput_2 {
    /** ISO date (YYYY-MM-DD) the organisation commenced data processing. */
    commencementDate: string;
    /** Reference date to evaluate against (YYYY-MM-DD). Defaults to today. */
    asOf?: string;
    /** DCPMI tier; CAR applies to DCPMIs only. Omit to assume applicable. */
    tier?: DCPMITier;
}

export declare interface CAROptions {
    /** Default annual filing deadline (month is 1-12). Defaults to 31 March. */
    annualDeadline?: {
        month: number;
        day: number;
    };
    /** Per-year overrides for the annual deadline, e.g. `{ 2026: '2026-05-30' }`. */
    deadlineOverrides?: Record<number, string>;
    /** Months after commencement the initial audit is due. Defaults to 15. */
    initialAuditWithinMonths?: number;
}

declare interface CAROptions_2 {
    /** Default annual filing deadline (month is 1-12). Defaults to 31 March. */
    annualDeadline?: {
        month: number;
        day: number;
    };
    /** Per-year overrides for the annual deadline, e.g. `{ 2026: '2026-05-30' }`. */
    deadlineOverrides?: Record<number, string>;
    /** Months after commencement the initial audit is due. Defaults to 15. */
    initialAuditWithinMonths?: number;
}

export declare interface ComplianceAuditReturn {
    /** Whether CAR applies (false for non-DCPMI organisations). */
    applicable: boolean;
    schedule: {
        commencementDate: string;
        initialAuditWithinMonths: number;
        /** Commencement date + the initial-audit window. */
        initialAuditDueDate: string;
        /** The next annual filing deadline on or after `asOf`. */
        nextFilingDeadline: string;
        /** The year the next filing deadline falls in. */
        filingYear: number;
    };
    status: {
        /** Whether the initial-audit obligation has arisen (asOf ≥ due date). */
        initialAuditDue: boolean;
        /** Whole days from `asOf` to the next filing deadline. */
        daysUntilNextDeadline: number;
    };
    notes: string[];
    asOf: string;
}

declare interface ComplianceAuditReturn_2 {
    /** Whether CAR applies (false for non-DCPMI organisations). */
    applicable: boolean;
    schedule: {
        commencementDate: string;
        initialAuditWithinMonths: number;
        /** Commencement date + the initial-audit window. */
        initialAuditDueDate: string;
        /** The next annual filing deadline on or after `asOf`. */
        nextFilingDeadline: string;
        /** The year the next filing deadline falls in. */
        filingYear: number;
    };
    status: {
        /** Whether the initial-audit obligation has arisen (asOf ≥ due date). */
        initialAuditDue: boolean;
        /** Whole days from `asOf` to the next filing deadline. */
        daysUntilNextDeadline: number;
    };
    notes: string[];
    asOf: string;
}

/** A single gap found during NDPA compliance evaluation. */
declare interface ComplianceGap {
    /** Machine-readable requirement identifier. */
    requirementId: string;
    /** Human-readable name of the requirement. */
    requirement: string;
    /** Reference to the relevant NDPA section. */
    ndpaSection: string;
    /** How severe the gap is. */
    severity: 'critical' | 'important' | 'recommended';
    /** Explanation of what is missing. */
    message: string;
    /** Suggested fix type for the UI. */
    fixType: 'add_section' | 'add_content' | 'fill_field';
    /** Label for the fix action button. */
    fixLabel: string;
    /** Pre-written content the user can insert to close the gap. */
    suggestedContent?: string;
}

export declare interface ComplianceInput {
    consent: {
        hasConsentMechanism: boolean;
        hasPurposeSpecification: boolean;
        hasWithdrawalMechanism: boolean;
        hasMinorProtection: boolean;
        consentRecordsRetained: boolean;
    };
    dsr: {
        hasRequestMechanism: boolean;
        supportsAccess: boolean;
        supportsRectification: boolean;
        supportsErasure: boolean;
        supportsPortability: boolean;
        supportsObjection: boolean;
        /** Expected max response time in days (>30 counts as a gap) */
        responseTimelineDays: number;
    };
    dpia: {
        conductedForHighRisk: boolean;
        documentedRisks: boolean;
        mitigationMeasures: boolean;
    };
    breach: {
        hasNotificationProcess: boolean;
        notifiesWithin72Hours: boolean;
        hasRiskAssessment: boolean;
        hasRecordKeeping: boolean;
    };
    policy: {
        hasPrivacyPolicy: boolean;
        isPubliclyAccessible: boolean;
        /** ISO date string (YYYY-MM-DD); >13 months old counts as a gap */
        lastUpdated: string;
        coversAllSections: boolean;
    };
    lawfulBasis: {
        documentedForAllProcessing: boolean;
        hasLegitimateInterestAssessment: boolean;
    };
    crossBorder: {
        hasTransferMechanisms: boolean;
        adequacyAssessed: boolean;
        ndpcApprovalObtained: boolean;
    };
    ropa: {
        maintained: boolean;
        includesAllProcessing: boolean;
        /** ISO date string (YYYY-MM-DD); >6 months since review counts as a gap */
        lastReviewed: string;
    };
}

declare interface ComplianceInput_2 {
    consent: {
        hasConsentMechanism: boolean;
        hasPurposeSpecification: boolean;
        hasWithdrawalMechanism: boolean;
        hasMinorProtection: boolean;
        consentRecordsRetained: boolean;
    };
    dsr: {
        hasRequestMechanism: boolean;
        supportsAccess: boolean;
        supportsRectification: boolean;
        supportsErasure: boolean;
        supportsPortability: boolean;
        supportsObjection: boolean;
        /** Expected max response time in days (>30 counts as a gap) */
        responseTimelineDays: number;
    };
    dpia: {
        conductedForHighRisk: boolean;
        documentedRisks: boolean;
        mitigationMeasures: boolean;
    };
    breach: {
        hasNotificationProcess: boolean;
        notifiesWithin72Hours: boolean;
        hasRiskAssessment: boolean;
        hasRecordKeeping: boolean;
    };
    policy: {
        hasPrivacyPolicy: boolean;
        isPubliclyAccessible: boolean;
        /** ISO date string (YYYY-MM-DD); >13 months old counts as a gap */
        lastUpdated: string;
        coversAllSections: boolean;
    };
    lawfulBasis: {
        documentedForAllProcessing: boolean;
        hasLegitimateInterestAssessment: boolean;
    };
    crossBorder: {
        hasTransferMechanisms: boolean;
        adequacyAssessed: boolean;
        ndpcApprovalObtained: boolean;
    };
    ropa: {
        maintained: boolean;
        includesAllProcessing: boolean;
        /** ISO date string (YYYY-MM-DD); >6 months since review counts as a gap */
        lastReviewed: string;
    };
}

/**
 * Compliance Score Engine
 *
 * Evaluates an organisation's NDPA compliance posture across eight modules and
 * returns a scored, rated report with per-module breakdowns and sorted
 * recommendations.
 *
 * Pure utility — zero React dependency.
 */
declare type ComplianceRating = 'excellent' | 'good' | 'needs-work' | 'critical';

/**
 * Compliance Score Engine
 *
 * Evaluates an organisation's NDPA compliance posture across eight modules and
 * returns a scored, rated report with per-module breakdowns and sorted
 * recommendations.
 *
 * Pure utility — zero React dependency.
 */
declare type ComplianceRating_2 = 'excellent' | 'good' | 'needs-work' | 'critical';

export declare interface ComplianceReport {
    /** Overall compliance score, 0–100 */
    score: number;
    /** Rating bucket */
    rating: ComplianceRating_2;
    /** Per-module breakdown keyed by module name */
    modules: Record<string, ModuleScore_2>;
    /** Recommendations sorted by priority (critical first) */
    recommendations: Recommendation_2[];
    /** Top-level regulatory references */
    regulatoryReferences: RegulatoryReference_2[];
    /** ISO date of when the report was generated */
    generatedAt: string;
}

declare interface ComplianceReport_2 {
    /** Overall compliance score, 0–100 */
    score: number;
    /** Rating bucket */
    rating: ComplianceRating;
    /** Per-module breakdown keyed by module name */
    modules: Record<string, ModuleScore>;
    /** Recommendations sorted by priority (critical first) */
    recommendations: Recommendation[];
    /** Top-level regulatory references */
    regulatoryReferences: RegulatoryReference[];
    /** ISO date of when the report was generated */
    generatedAt: string;
}

/** Result of evaluating a policy against NDPA requirements. */
declare interface ComplianceResult {
    /** Points earned. */
    score: number;
    /** Maximum achievable points (115). */
    maxScore: number;
    /** Percentage score (0-100). */
    percentage: number;
    /** Overall compliance rating. */
    rating: 'compliant' | 'nearly_compliant' | 'not_compliant';
    /** List of identified compliance gaps. */
    gaps: ComplianceGap[];
    /** List of requirement ids that passed. */
    passed: string[];
}

/**
 * Consent types aligned with NDPA 2023 Section 25-26
 * Consent must be freely given, specific, informed, and unambiguous
 */
/**
 * Represents a consent option that can be presented to users
 */
export declare interface ConsentOption {
    /** Unique identifier for the consent option */
    id: string;
    /** Display label for the consent option */
    label: string;
    /** Detailed description of what this consent option covers */
    description: string;
    /** Whether this consent option is required (cannot be declined) */
    required: boolean;
    /**
     * The specific purpose for which data will be processed
     * NDPA Section 25(2) requires consent to be specific to each purpose
     */
    purpose: string;
    /**
     * Default state of the consent option
     * @default false
     */
    defaultValue?: boolean;
    /**
     * Categories of personal data covered by this consent option
     */
    dataCategories?: string[];
}

/**
 * Represents the user's consent settings
 */
export declare interface ConsentSettings {
    /** Map of consent option IDs to boolean values indicating consent status */
    consents: Record<string, boolean>;
    /** Timestamp when consent was last updated */
    timestamp: number;
    /** Version of the consent form that was accepted */
    version: string;
    /** Method used to collect consent (e.g., "banner", "settings", "api") */
    method: string;
    /** Whether the user has actively made a choice (as opposed to default settings) */
    hasInteracted: boolean;
    /**
     * The lawful basis under which processing is conducted
     * Required by NDPA Section 25(1)
     */
    lawfulBasis?: LawfulBasisType;
}

/**
 * Represents the storage mechanism for consent settings
 */
export declare interface ConsentStorageOptions {
    /**
     * Storage key for consent settings
     * @default "ndpr_consent"
     */
    storageKey?: string;
    /**
     * Storage type to use
     * @default "localStorage"
     */
    storageType?: 'localStorage' | 'sessionStorage' | 'cookie';
    /**
     * Cookie options (only used when storageType is "cookie")
     */
    cookieOptions?: {
        /** Domain for the cookie */
        domain?: string;
        /**
         * Path for the cookie
         * @default "/"
         */
        path?: string;
        /**
         * Expiration days for the cookie
         * @default 365
         */
        expires?: number;
        /**
         * Whether the cookie should be secure
         * @default true
         */
        secure?: boolean;
        /**
         * SameSite attribute for the cookie
         * @default "Lax"
         */
        sameSite?: 'Strict' | 'Lax' | 'None';
    };
}

/** How a present cookie was classified. */
export declare type CookieMatchSource = 'declared' | 'known' | 'none';

/** How a present cookie was classified. */
declare type CookieMatchSource_2 = 'declared' | 'known' | 'none';

export declare interface CookieScanOptions {
    /**
     * The cookie string to scan, in `document.cookie` form (`a=1; b=2`).
     * Defaults to `document.cookie` in the browser, or `''` on the server.
     */
    cookieString?: string;
    /** Reference timestamp (epoch ms) recorded on the result. Defaults to `Date.now()`. */
    asOf?: number;
    /** Extra known cookies, checked before the built-in registry (so they can override it). */
    knownCookies?: DeclaredCookie[];
    /** Whether to fall back to the built-in known-cookie registry for undeclared cookies. @default true */
    useKnownRegistry?: boolean;
}

declare interface CookieScanOptions_2 {
    /**
     * The cookie string to scan, in `document.cookie` form (`a=1; b=2`).
     * Defaults to `document.cookie` in the browser, or `''` on the server.
     */
    cookieString?: string;
    /** Reference timestamp (epoch ms) recorded on the result. Defaults to `Date.now()`. */
    asOf?: number;
    /** Extra known cookies, checked before the built-in registry (so they can override it). */
    knownCookies?: DeclaredCookie_2[];
    /** Whether to fall back to the built-in known-cookie registry for undeclared cookies. @default true */
    useKnownRegistry?: boolean;
}

export declare interface CookieScanResult {
    /** When the scan ran (epoch ms). */
    scannedAt: number;
    /** Number of cookies present. */
    total: number;
    /** Every present cookie, classified. */
    cookies: ScannedCookie[];
    /** Cookies that matched one of your declared cookies. */
    declared: ScannedCookie[];
    /** Cookies present but NOT in your declaration — the compliance gap. */
    undeclared: ScannedCookie[];
    /** Undeclared cookies the built-in registry could still identify. */
    identified: ScannedCookie[];
    /** Undeclared cookies that could not be identified at all. */
    unknown: ScannedCookie[];
    /** Present cookies grouped by resolved category; unclassified cookies go under `uncategorized`. */
    byCategory: Record<string, ScannedCookie[]>;
    /** True when there are no undeclared cookies. */
    complete: boolean;
}

declare interface CookieScanResult_2 {
    /** When the scan ran (epoch ms). */
    scannedAt: number;
    /** Number of cookies present. */
    total: number;
    /** Every present cookie, classified. */
    cookies: ScannedCookie_2[];
    /** Cookies that matched one of your declared cookies. */
    declared: ScannedCookie_2[];
    /** Cookies present but NOT in your declaration — the compliance gap. */
    undeclared: ScannedCookie_2[];
    /** Undeclared cookies the built-in registry could still identify. */
    identified: ScannedCookie_2[];
    /** Undeclared cookies that could not be identified at all. */
    unknown: ScannedCookie_2[];
    /** Present cookies grouped by resolved category; unclassified cookies go under `uncategorized`. */
    byCategory: Record<string, ScannedCookie_2[]>;
    /** True when there are no undeclared cookies. */
    complete: boolean;
}

/**
 * Summary of cross-border transfer compliance
 */
export declare interface CrossBorderSummary {
    /** Total number of active transfers */
    totalActiveTransfers: number;
    /** Breakdown by transfer mechanism */
    byMechanism: Record<TransferMechanism, number>;
    /** Breakdown by adequacy status */
    byAdequacy: Record<AdequacyStatus, number>;
    /** Transfers pending NDPC approval */
    pendingApproval: CrossBorderTransfer[];
    /** Transfers due for review */
    dueForReview: CrossBorderTransfer[];
    /** Transfers missing TIA */
    missingTIA: CrossBorderTransfer[];
    /** High-risk transfers */
    highRiskTransfers: CrossBorderTransfer[];
    /** Last updated timestamp */
    lastUpdated: number;
}

/**
 * Represents a cross-border data transfer record
 */
export declare interface CrossBorderTransfer {
    /** Unique identifier */
    id: string;
    /** Destination country or territory */
    destinationCountry: string;
    /** ISO country code */
    destinationCountryCode?: string;
    /** Adequacy status of the destination */
    adequacyStatus: AdequacyStatus;
    /** The transfer mechanism being relied upon */
    transferMechanism: TransferMechanism;
    /** Categories of personal data being transferred */
    dataCategories: string[];
    /** Whether sensitive personal data is included */
    includesSensitiveData: boolean;
    /** Estimated number of data subjects whose data is transferred */
    estimatedDataSubjects?: number;
    /** Name of the recipient organization */
    recipientOrganization: string;
    /** Contact details of the recipient */
    recipientContact: {
        name: string;
        email: string;
        phone?: string;
        address?: string;
    };
    /** Purpose of the data transfer */
    purpose: string;
    /** Safeguards in place to protect the data */
    safeguards: string[];
    /** Risk assessment summary */
    riskAssessment: string;
    /** Risk level of the transfer */
    riskLevel: 'low' | 'medium' | 'high';
    /** NDPC approval details (required for some transfer mechanisms) */
    ndpcApproval?: {
        required: boolean;
        applied: boolean;
        approved?: boolean;
        referenceNumber?: string;
        appliedAt?: number;
        approvedAt?: number;
    };
    /** Whether a Transfer Impact Assessment has been conducted */
    tiaCompleted: boolean;
    /** Reference to the TIA document */
    tiaReference?: string;
    /** Frequency of the transfer */
    frequency: 'one_time' | 'periodic' | 'continuous';
    /** Start date of the transfer */
    startDate: number;
    /** End date of the transfer (if applicable) */
    endDate?: number;
    /** Status of the transfer */
    status: 'active' | 'suspended' | 'terminated' | 'pending_approval';
    /** Timestamp when the record was created */
    createdAt: number;
    /** Timestamp when the record was last updated */
    updatedAt: number;
    /** Next review date */
    reviewDate?: number;
}

/** A user-defined section added to the policy outside the generated ones. */
declare interface CustomSection {
    id: string;
    title: string;
    content: string;
    order: number;
    required: false;
}

/** A logical category of personal data the organisation may collect. */
declare interface DataCategory {
    /** Machine-readable identifier. */
    id: string;
    /** Human-readable label shown in the wizard. */
    label: string;
    /** Grouping for display and compliance checks. */
    group: 'identity' | 'financial' | 'behavioral' | 'sensitive' | 'children';
    /** Specific data points within this category. */
    dataPoints: string[];
    /** Whether this category is currently selected by the user. */
    selected: boolean;
}

export declare interface DCPMIClassification {
    /** Registration tier (or `'none'` when not a DCPMI). */
    tier: DCPMITier_2;
    /** Whether the organisation is a Data Controller/Processor of Major Importance. */
    isDCPMI: boolean;
    /** Annual registration fee in Nigerian Naira (0 when not a volume-tiered DCPMI). */
    annualFeeNGN: number;
    registration: {
        /** Whether NDPC registration is required. */
        required: boolean;
        /** OHL renews registration annually; UHL/EHL register once and file CAR annually. */
        renewsAnnually: boolean;
    };
    compliance: {
        /** Whether the organisation must file annual Compliance Audit Returns (CAR). */
        auditReturnsAnnual: boolean;
        /** Initial compliance audit is due within this many months of commencing processing. */
        initialAuditWithinMonths: number;
    };
    /** Human-readable caveats and next steps. */
    notes: string[];
    /** The count actually used for classification, after defensive normalisation. */
    dataSubjectsConsidered: number;
}

declare interface DCPMIClassification_2 {
    /** Registration tier (or `'none'` when not a DCPMI). */
    tier: DCPMITier;
    /** Whether the organisation is a Data Controller/Processor of Major Importance. */
    isDCPMI: boolean;
    /** Annual registration fee in Nigerian Naira (0 when not a volume-tiered DCPMI). */
    annualFeeNGN: number;
    registration: {
        /** Whether NDPC registration is required. */
        required: boolean;
        /** OHL renews registration annually; UHL/EHL register once and file CAR annually. */
        renewsAnnually: boolean;
    };
    compliance: {
        /** Whether the organisation must file annual Compliance Audit Returns (CAR). */
        auditReturnsAnnual: boolean;
        /** Initial compliance audit is due within this many months of commencing processing. */
        initialAuditWithinMonths: number;
    };
    /** Human-readable caveats and next steps. */
    notes: string[];
    /** The count actually used for classification, after defensive normalisation. */
    dataSubjectsConsidered: number;
}

export declare interface DCPMIClassificationOptions {
    thresholds?: Partial<DCPMIThresholds_2>;
    fees?: Partial<DCPMIFees_2>;
}

declare interface DCPMIClassificationOptions_2 {
    thresholds?: Partial<DCPMIThresholds>;
    fees?: Partial<DCPMIFees>;
}

declare interface DCPMIFees {
    UHL: number;
    EHL: number;
    OHL: number;
}

declare interface DCPMIFees_2 {
    UHL: number;
    EHL: number;
    OHL: number;
}

export declare interface DCPMIInput {
    /** Distinct data subjects whose data was processed in the relevant six-month window. */
    dataSubjectsInSixMonths?: number;
    /** True if the Commission has separately designated/listed the organisation as a DCPMI. */
    isDesignated?: boolean;
}

declare interface DCPMIInput_2 {
    /** Distinct data subjects whose data was processed in the relevant six-month window. */
    dataSubjectsInSixMonths?: number;
    /** True if the Commission has separately designated/listed the organisation as a DCPMI. */
    isDesignated?: boolean;
}

declare interface DCPMIThresholds {
    /** Lower bound (inclusive) for OHL. */
    ohl: number;
    /** Lower bound (inclusive) for EHL. */
    ehl: number;
    /** A count strictly greater than this is UHL. */
    uhl: number;
}

declare interface DCPMIThresholds_2 {
    /** Lower bound (inclusive) for OHL. */
    ohl: number;
    /** Lower bound (inclusive) for EHL. */
    ehl: number;
    /** A count strictly greater than this is UHL. */
    uhl: number;
}

/**
 * Data Controller/Processor of Major Importance (DCPMI) classification under the
 * NDPC General Application and Implementation Directive (GAID) 2025.
 *
 * Volume-based tiers — data subjects processed within a six-month window:
 *   - UHL (Ultra High Level):    more than 5,000  → ₦250,000 / year
 *   - EHL (Extra High Level):    1,000 – 5,000    → ₦100,000 / year
 *   - OHL (Ordinary High Level): 200 – 999        → ₦10,000  / year
 *   - below 200:                 not a DCPMI by volume
 *
 * Boundaries: the 1,000 mark resolves to EHL (so OHL is 200–999); UHL is
 * strictly greater than 5,000 (so 5,000 itself is EHL). The NDPC has revised
 * classification metrics before and shifts filing deadlines, so thresholds and
 * fees are configurable — treat the defaults as the September 2025 GAID
 * baseline, not a constant.
 *
 * `isDesignated` marks an organisation the Commission has otherwise listed as a
 * DCPMI; it is then a DCPMI regardless of volume. Below the volume tiers such an
 * organisation is reported as `'listed'` with the fee left at 0 and a note to
 * confirm the applicable tier/fee with the NDPC.
 *
 * @see NDPC General Application and Implementation Directive (GAID) 2025
 * @see NDPC Guidance Notice on the Registration of Data Controllers and Processors of Major Importance
 */
declare type DCPMITier = 'UHL' | 'EHL' | 'OHL' | 'listed' | 'none';

/**
 * Data Controller/Processor of Major Importance (DCPMI) classification under the
 * NDPC General Application and Implementation Directive (GAID) 2025.
 *
 * Volume-based tiers — data subjects processed within a six-month window:
 *   - UHL (Ultra High Level):    more than 5,000  → ₦250,000 / year
 *   - EHL (Extra High Level):    1,000 – 5,000    → ₦100,000 / year
 *   - OHL (Ordinary High Level): 200 – 999        → ₦10,000  / year
 *   - below 200:                 not a DCPMI by volume
 *
 * Boundaries: the 1,000 mark resolves to EHL (so OHL is 200–999); UHL is
 * strictly greater than 5,000 (so 5,000 itself is EHL). The NDPC has revised
 * classification metrics before and shifts filing deadlines, so thresholds and
 * fees are configurable — treat the defaults as the September 2025 GAID
 * baseline, not a constant.
 *
 * `isDesignated` marks an organisation the Commission has otherwise listed as a
 * DCPMI; it is then a DCPMI regardless of volume. Below the volume tiers such an
 * organisation is reported as `'listed'` with the fee left at 0 and a note to
 * confirm the applicable tier/fee with the NDPC.
 *
 * @see NDPC General Application and Implementation Directive (GAID) 2025
 * @see NDPC Guidance Notice on the Registration of Data Controllers and Processors of Major Importance
 */
declare type DCPMITier_2 = 'UHL' | 'EHL' | 'OHL' | 'listed' | 'none';

/**
 * Cookie scanner — audits the cookies actually present in the browser against
 * the cookies you have declared, surfacing undeclared cookies that put you out
 * of step with your cookie notice (NDPA 2023 S.25-26 / NDPC GAID 2025 on
 * specific, informed consent).
 *
 * Pure and DOM-optional: pass `cookieString` to scan an arbitrary value (a
 * `Cookie:` header on the server, a test fixture), or call it in the browser
 * and it reads `document.cookie`. Safe to import from a server bundle.
 */
/** A cookie you declare against a consent category. */
export declare interface DeclaredCookie {
    /** Exact cookie name, a prefix (with `prefix: true`), or a RegExp matched against the name. */
    name: string | RegExp;
    /** Consent category this cookie belongs to (e.g. 'necessary', 'analytics', 'marketing'). */
    category: string;
    /** Who sets the cookie (e.g. 'Google Analytics'). */
    provider?: string;
    /** What the cookie is used for — surfaced in your cookie policy. */
    purpose?: string;
    /** Treat a string `name` as a prefix match instead of an exact match. Ignored for RegExp names. */
    prefix?: boolean;
}

/**
 * Cookie scanner — audits the cookies actually present in the browser against
 * the cookies you have declared, surfacing undeclared cookies that put you out
 * of step with your cookie notice (NDPA 2023 S.25-26 / NDPC GAID 2025 on
 * specific, informed consent).
 *
 * Pure and DOM-optional: pass `cookieString` to scan an arbitrary value (a
 * `Cookie:` header on the server, a test fixture), or call it in the browser
 * and it reads `document.cookie`. Safe to import from a server bundle.
 */
/** A cookie you declare against a consent category. */
declare interface DeclaredCookie_2 {
    /** Exact cookie name, a prefix (with `prefix: true`), or a RegExp matched against the name. */
    name: string | RegExp;
    /** Consent category this cookie belongs to (e.g. 'necessary', 'analytics', 'marketing'). */
    category: string;
    /** Who sets the cookie (e.g. 'Google Analytics'). */
    provider?: string;
    /** What the cookie is used for — surfaced in your cookie policy. */
    purpose?: string;
    /** Treat a string `name` as a prefix match instead of an exact match. Ignored for RegExp names. */
    prefix?: boolean;
}

/** Options for DOCX export of the finalised policy. */
declare interface DOCXExportOptions {
    includeTOC?: boolean;
    filename?: string;
}

/** A map of question IDs to their answer values */
export declare type DPIAAnswerMap = Record<string, DPIAAnswerValue>;

/** Possible value types for a DPIA answer */
export declare type DPIAAnswerValue = string | number | boolean | string[];

/**
 * Data Protection Impact Assessment types aligned with NDPA 2023 Section 28
 * A DPIA is required when processing is likely to result in high risk to data subjects
 */
/**
 * Represents a question in the DPIA questionnaire
 */
declare interface DPIAQuestion {
    /** Unique identifier for the question */
    id: string;
    /** The text of the question */
    text: string;
    /** Additional guidance for answering the question */
    guidance?: string;
    /** Type of input required for the answer */
    type: 'text' | 'textarea' | 'select' | 'radio' | 'checkbox' | 'scale';
    /** Options for select, radio, or checkbox questions */
    options?: Array<{
        value: string;
        label: string;
        riskLevel?: 'low' | 'medium' | 'high';
    }>;
    /** For scale questions, the minimum value */
    minValue?: number;
    /** For scale questions, the maximum value */
    maxValue?: number;
    /** For scale questions, labels for the scale points */
    scaleLabels?: Record<number, string>;
    /** Whether the question is required */
    required: boolean;
    /** Risk level associated with this question */
    riskLevel?: 'low' | 'medium' | 'high';
    /** Whether this question triggers additional questions based on the answer */
    hasDependentQuestions?: boolean;
    /** Conditions that determine when this question should be shown */
    showWhen?: Array<{
        questionId: string;
        operator: 'equals' | 'contains' | 'greaterThan' | 'lessThan';
        value: string | number | boolean;
    }>;
}

/**
 * Represents the result of a completed DPIA
 */
export declare interface DPIAResult {
    /** Unique identifier for the DPIA */
    id: string;
    /** Title of the DPIA */
    title: string;
    /** Description of the processing activity being assessed */
    processingDescription: string;
    /** Timestamp when the DPIA was started */
    startedAt: number;
    /** Timestamp when the DPIA was completed */
    completedAt?: number;
    /** Person responsible for conducting the DPIA */
    assessor: {
        name: string;
        role: string;
        email: string;
    };
    /** Answers to all questions in the DPIA */
    answers: Record<string, string | number | boolean | string[]>;
    /** Risks identified in the DPIA */
    risks: DPIARisk[];
    /** Overall risk level of the processing activity */
    overallRiskLevel: 'low' | 'medium' | 'high' | 'critical';
    /** Whether the DPIA concluded that the processing can proceed */
    canProceed: boolean;
    /** Reasons why the processing can or cannot proceed */
    conclusion: string;
    /** Recommendations for the processing activity */
    recommendations?: string[];
    /** Next review date for the DPIA */
    reviewDate?: number;
    /** Version of the DPIA questionnaire used */
    version: string;
    /**
     * Whether prior consultation with NDPC is required
     * Per NDPA Section 28(2), consultation is required when DPIA indicates high residual risk
     */
    ndpcConsultationRequired?: boolean;
    /** Date when NDPC consultation was initiated */
    ndpcConsultationDate?: number;
    /** Reference number from NDPC consultation */
    ndpcConsultationReference?: string;
    /**
     * The lawful basis for the processing activity being assessed
     */
    lawfulBasis?: string;
    /**
     * Whether this DPIA involves cross-border data transfers
     */
    involvesCrossBorderTransfer?: boolean;
}

/**
 * Represents a risk identified in the DPIA
 */
export declare interface DPIARisk {
    /** Unique identifier for the risk */
    id: string;
    /** Description of the risk */
    description: string;
    /** Likelihood of the risk occurring (1-5) */
    likelihood: number;
    /** Impact if the risk occurs (1-5) */
    impact: number;
    /** Overall risk score (likelihood * impact) */
    score: number;
    /** Risk level based on the score */
    level: 'low' | 'medium'