@tantainnovative/ndpr-toolkit/dist/hooks.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[];
};

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

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

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

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

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

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

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

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

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

export declare interface ComplianceReport {
    /** 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';

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

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

/**
 * 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;
    /** 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>;
    fees?: Partial<DCPMIFees>;
}

declare interface DCPMIFees {
    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 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;
}

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

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

/** 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' | 'high' | 'critical';
    /** Measures to mitigate the risk */
    mitigationMeasures?: string[];
    /** Whether the risk has been mitigated */
    mitigated: boolean;
    /** Residual risk score after mitigation */
    residualScore?: number;
    /** Questions that identified this risk */
    relatedQuestionIds: string[];
}

/**
 * Represents a section in the DPIA questionnaire
 */
declare interface DPIASection {
    /** Unique identifier for the section */
    id: string;
    /** Title of the section */
    title: string;
    /** Description of the section */
    description?: string;
    /** Questions in this section */
    questions: DPIAQuestion[];
    /** Order of the section in the questionnaire */
    order: number;
}

/**
 * Represents a data subject request
 */
export declare interface DSRRequest {
    /** Unique identifier for the request */
    id: string;
    /** Type of request */
    type: DSRType;
    /** Current status of the request */
    status: DSRStatus;
    /** Timestamp when the request was submitted */
    createdAt: number;
    /** Timestamp when the request was last updated */
    updatedAt: number;
    /** Timestamp when the request was completed (if applicable) */
    completedAt?: number;
    /** Timestamp when the identity was verified (if applicable) */
    verifiedAt?: number;
    /**
     * Due date for responding to the request (timestamp)
     * NDPA requires response within 30 days of receipt
     */
    dueDate?: number;
    /** Description or details of the request */
    description?: string;
    /**
     * The lawful basis under which the data was originally processed
     * Relevant for evaluating objection and erasure requests
     */
    lawfulBasis?: string;
    /** Data subject information */
    subject: {
        name: string;
        email: string;
        phone?: string;
        identifierValue?: string;
        identifierType?: string;
    };
    /** Additional information provided by the data subject */
    additionalInfo?: Record<string, string | number | boolean | null>;
    /** Notes added by staff processing the request */
    internalNotes?: Array<{
        timestamp: number;
        author: string;
        note: string;
    }>;
    /** Verification status */
    verification?: {
        verified: boolean;
        method?: string;
        verifiedAt?: number;
        verifiedBy?: string;
    };
    /** Reason for rejection (if status is 'rejected') */
    rejectionReason?: string;
    /** Files attached to the request */
    attachments?: Array<{
        id: string;
        name: string;
        type: string;
        url: string;
        addedAt: number;
    }>;
    /**
     * Whether an extension was requested for this DSR
     * NDPA allows a one-time extension of 30 days with justification
     */
    extensionRequested?: boolean;
    /** Reason for the extension, if requested */
    extensionReason?: string;
}

/**
 * Status of a data subject request
 */
export declare type DSRStatus = 'pending' | 'awaitingVerification' | 'inProgress' | 'completed' | 'rejected';

/**
 * Data Subject Rights types aligned with NDPA 2023 Part VI (Sections 34-38)
 * and the related provisions in Part V (Section 27 — information to the data subject)
 * and Part X (Section 46 — complaint to the Commission).
 *
 * Note: These are guidance labels — not legal advice. Verify with your DPO or counsel.
 */
/**
 * Types of data subject requests per NDPA Part VI
 * - 'information': Right to be informed (Section 27 — provision of information; Section 34(1)(a))
 * - 'access': Right of access / confirmation + data copy (Section 34(1)(a)–(b))
 * - 'rectification': Right to rectification (Section 34(1)(c))
 * - 'erasure': Right to erasure (Section 34(1)(d), Section 34(2))
 * - 'restriction': Right to restrict processing (Section 34(1)(e))
 * - 'portability': Right to data portability (Section 38)
 * - 'objection': Right to object (Section 36)
 * - 'automated_decision_making': Rights re. automated decisions / profiling (Section 37)
 * - 'withdraw_consent': Right to withdraw consent (Section 35)
 */
export declare type DSRType = 'information' | 'access' | 'rectification' | 'erasure' | 'restriction' | 'portability' | 'objection' | 'automated_decision_making' | 'withdraw_consent';

declare type EffortLevel = 'low' | 'medium' | 'high';

/** Options for HTML export of the finalised policy. */
declare interface HTMLExportOptions {
    includeStyles?: boolean;
    includePrintCSS?: boolean;
    customCSS?: string;
    /**
     * Theme controlling the embedded design tokens.
     *
     * - `'light'` (default): emits the light token palette only. No
     *   `prefers-color-scheme: dark` block is included, so a visitor's OS
     *   dark-mode setting will NOT recolour the policy. This is the right
     *   default for an embedded compliance widget — most consumer host sites
     *   are single-theme and Shadow DOM does not isolate `prefers-color-scheme`.
     * - `'dark'`: emits the dark token palette as the primary style.
     * - `'auto'`: emits light tokens plus a `@media (prefers-color-scheme: dark)`
     *   block that swaps to dark on the user's OS preference. Use this when
     *   your host site genuinely follows OS dark mode and you want the policy
     *   to match.
     *
     * Pre-3.4.1 the export effectively behaved like `'auto'` unconditionally,
     * which leaked dark colours into light-only host sites via Shadow DOM.
     *
     * @default 'light'
     */
    theme?: 'light' | 'dark' | 'auto';
}

/**
 * Policy engine types for the adaptive privacy policy generator.
 * These types power the wizard-driven policy builder, compliance checker,
 * and export functionality — all aligned with the NDPA 2023.
 */

/** Industry verticals with sector-specific compliance requirements. */
declare type Industry = 'fintech' | 'healthcare' | 'ecommerce' | 'saas' | 'education' | 'government' | 'other';

/**
 * 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 LawfulBasis = 'consent' | 'contract' | 'legal_obligation' | 'vital_interests' | 'public_interest' | 'legitimate_interests';

/**
 * 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<LawfulBasis, 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 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
 */
declare interface LawfulBasisValidationResult {
    isValid: boolean;
    errors: string[];
    warnings: string[];
}

declare interface ModuleScore {
    /** Module name (e.g. "consent") */
    name: string;
    /** Raw module score 0-100 */
    score: number;
    /** Maximum possible score for this module (always 100) */
    maxScore: number;
    /** Weighted contribution to the overall score */
    weightedScore: number;
    /** NDPA sections this module maps to */
    ndpaSections: string[];
    /** Gaps found — list of human-readable gap descriptions */
    gaps: string[];
}

/**
 * Represents notification requirements for a data breach per NDPA Section 40
 */
export declare 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 organization information for a privacy policy
 */
export declare interface OrganizationInfo {
    /** Name of the organization */
    name: string;
    /** Website URL of the organization */
    website: string;
    /** Contact email for privacy inquiries */
    privacyEmail: string;
    /** Physical address of the organization */
    address?: string;
    /** Phone number for privacy inquiries */
    privacyPhone?: string;
    /** Name of the Data Protection Officer */
    dpoName?: string;
    /** Email of the Data Protection Officer */
    dpoEmail?: string;
    /** Industry or sector of the organization */
    industry?: string;
    /** NDPC registration number (if registered) */
    ndpcRegistrationNumber?: string;
}

/** Organisation size tiers — affects complexity of generated language. */
declare type OrgSize = 'startup' | 'midsize' | 'enterprise';

/** Options for PDF export of the finalised policy. */
declare interface PDFExportOptions {
    includeCoverPage?: boolean;
    includeTOC?: boolean;
    includeComplianceBadge?: boolean;
    logoUrl?: string;
    filename?: string;
}

/** Represents an in-progress policy being built in the wizard. */
declare interface PolicyDraft {
    /** Unique identifier for the draft. */
    id: string;
    /** The template context driving section generation. */
    templateContext: TemplateContext;
    /** Custom sections added by the user. */
    customSections: CustomSection[];
    /** Per-section content overrides keyed by section id. */
    sectionOverrides: Record<string, string>;
    /** Ordered list of section ids defining the final order. */
    sectionOrder: string[];
    /** Current wizard step (0-indexed). */
    currentStep: number;
    /** Timestamp of the last save. */
    lastSavedAt: number;
    /** The draft is always in "draft" status until finalised. */
    status: 'draft';
}

/**
 * Privacy policy types aligned with NDPA 2023
 * Privacy policies must clearly inform data subjects of their rights under the NDPA
 */
/**
 * Represents a section in a privacy policy
 */
export declare interface PolicySection {
    /** Unique identifier for the section */
    id: string;
    /** Title of the section */
    title: string;
    /** Description of the section */
    description?: string;
    /** Order of the section in the policy */
    order?: number;
    /** Whether the section is required by NDPA */
    required: boolean;
    /** Template text for the section */
    template: string;
    /**
     * Default content for the section (legacy field)
     * @deprecated Use template instead
     */
    defaultContent?: string;
    /**
     * Custom content for the section (overrides default content)
     * @deprecated Use template instead
     */
    customContent?: string;
    /** Whether the section is included in the policy */
    included: boolean;
    /** Variables that can be used in the section content */
    variables?: string[];
}

/**
 * Represents a privacy policy template
 */
declare interface PolicyTemplate {
    /** Unique identifier for the template */
    id: string;
    /** Name of the template */
    name: string;
    /** Description of the template */
    description: string;
    /** Type of organization the template is designed for */
    organizationType: 'business' | 'nonprofit' | 'government' | 'educational';
    /** Sections included in the template */
    sections: PolicySection[];
    /** Variables used across the template */
    variables: Record<string, {
        name: string;
        description: string;
        required: boolean;
        defaultValue?: string;
    }>;
    /** Version of the template */
    version: string;
    /** Last updated date of the template */
    lastUpdated: number;
    /**
     * Whether this template is NDPA 2023 compliant
     */
    ndpaCompliant: boolean;
}

/**
 * Represents a generated privacy policy
 */
export declare interface PrivacyPolicy {
    /** Unique identifier for the policy */
    id: string;
    /** Title of the policy */
    title: string;
    /** Template used to generate the policy */
    templateId: string;
    /** Organization information */
    organizationInfo: OrganizationInfo;
    /** Sections of the policy */
    sections: PolicySection[];
    /** Values for the variables used in the policy */
    variableValues: Record<string, string>;
    /** Effective date of the policy */
    effectiveDate: number;
    /** Last updated date of the policy */
    lastUpdated: number;
    /** Version of the policy */
    version: string;
    /**
     * Applicable legal frameworks
     */
    applicableFrameworks?: ('ndpa' | 'ndpr' | 'gdpr' | 'ccpa')[];
}

/**
 * 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: LawfulBasis;
    /** 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;
    };
}

/** Lawful processing purposes recognised under the NDPA. */
declare type ProcessingPurpose = 'service_delivery' | 'marketing' | 'analytics' | 'research' | 'legal_compliance' | 'fraud_prevention';

/**
 * 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