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

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

import { ErrorInfo } from 'react';
import React__default from 'react';
import { ReactNode } from 'react';
import { RefObject } from 'react';

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

export declare interface ApiAdapterErrorContext<T = unknown> {
    /** Which adapter operation triggered this — `load`, `save`, or `remove`. */
    method: ApiAdapterMethod;
    /** The endpoint URL that failed. */
    endpoint: string;
    /** Underlying error (for network failures / parse errors). */
    error?: unknown;
    /** Response object, if a response was received. */
    response?: Response;
    /** HTTP status code, if available. */
    status?: number;
    /** For `save`, the payload that failed to send. */
    payload?: T;
    /** Which retry attempt this is (0 = first try). Capped at `retry.attempts`. */
    attempt: number;
}

export declare type ApiAdapterMethod = 'load' | 'save' | 'remove';

export declare interface ApiAdapterOptions<T = unknown> {
    /**
     * Extra HTTP headers to send with every request. Useful for `Authorization`,
     * `X-CSRF-Token`, `X-Requested-With`, etc.
     *
     * Can also be a function that returns headers, which lets you read a CSRF
     * token from the DOM/cookie at request time rather than at adapter
     * construction time.
     */
    headers?: Record<string, string> | (() => Record<string, string>);
    /**
     * Forwarded to fetch's `credentials` option. Defaults to `'same-origin'`
     * (the browser default). Set to `'include'` for cross-origin endpoints
     * that need cookies / auth.
     */
    credentials?: RequestCredentials;
    /**
     * HTTP method override for the load operation. Defaults to `'GET'`.
     */
    loadMethod?: 'GET' | 'POST';
    /**
     * HTTP method override for the save operation. Defaults to `'POST'`. Some
     * REST APIs prefer `'PUT'` for upsert semantics.
     */
    saveMethod?: 'POST' | 'PUT' | 'PATCH';
    /**
     * Transform the raw JSON response into the expected `T`. Useful for APIs
     * that wrap responses in `{ data: ... }` or similar envelopes. Called
     * after `res.json()`. If omitted, the parsed JSON is used as-is.
     */
    unwrap?: (raw: unknown) => T | null;
    /**
     * Retry policy for failed requests. Defaults to no retries (preserves the
     * pre-3.6.0 behaviour). When configured, applies to all three operations.
     */
    retry?: ApiAdapterRetryConfig;
    /**
     * Called when a request fails (after all retries exhausted). The adapter
     * still returns a graceful null/void result so the consuming hook
     * doesn't crash — this hook is for telemetry, toasts, or audit logging.
     */
    onError?: (ctx: ApiAdapterErrorContext<T>) => void;
    /**
     * Called when a request succeeds. Useful for cache invalidation,
     * analytics, or syncing other state.
     */
    onSuccess?: (ctx: ApiAdapterSuccessContext<T>) => void;
    /**
     * Per-request fetch options to merge into every request. Use this for
     * things `fetch` itself supports that aren't directly modelled above —
     * `signal`, `mode`, `cache`, `redirect`, etc.
     */
    fetchInit?: Omit<RequestInit, 'method' | 'headers' | 'body' | 'credentials'>;
}

export declare interface ApiAdapterRetryConfig {
    /**
     * Number of additional attempts after the initial request. Defaults to 0
     * (no retries). e.g. `attempts: 2` means up to 3 total requests.
     */
    attempts?: number;
    /**
     * Base delay in ms between attempts. Defaults to 250ms. The actual delay
     * uses exponential backoff: `baseDelayMs * 2^attempt`.
     */
    baseDelayMs?: number;
    /**
     * Predicate that decides whether to retry given the failure context. By
     * default we retry on network errors and 5xx responses, but not on 4xx
     * (those are client errors that won't fix themselves).
     */
    shouldRetry?: (ctx: ApiAdapterErrorContext<unknown>) => boolean;
}

export declare interface ApiAdapterSuccessContext<T = unknown> {
    /** Which adapter operation succeeded — `load`, `save`, or `remove`. */
    method: ApiAdapterMethod;
    /** The endpoint URL. */
    endpoint: string;
    /** Response object. */
    response: Response;
    /** For `load` operations, the parsed (and optionally unwrapped) data. */
    data?: T;
    /** For `save` operations, the payload that was sent. */
    payload?: T;
}

/**
 * Appends a single audit entry to the consent audit log in localStorage.
 * The log is append-only; existing entries are never modified.
 *
 * @param entry     - The audit entry to append
 * @param storageKey - Base storage key (the audit key is derived as `${storageKey}_audit`)
 */
export declare function appendAuditEntry(entry: ConsentAuditEntry, storageKey?: string): void;

/**
 * Assess a breach report against the NDPA S. 40 / GAID 2025 Article 33
 * notification requirements.
 */
export declare function assessBreachNotification(report: BreachReport, options?: BreachNotificationOptions): BreachNotificationAssessment;

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

/**
 * Assesses the risk level of a DPIA based on the identified risks
 * @param dpiaResult The DPIA result containing risks to assess
 * @returns Assessment result with overall risk level and recommendations
 */
export declare function assessDPIARisk(dpiaResult: DPIAResult): {
    overallRiskLevel: 'low' | 'medium' | 'high' | 'critical';
    requiresConsultation: boolean;
    canProceed: boolean;
    recommendations: string[];
};

/**
 * Performs a basic risk assessment of a cross-border transfer based on adequacy status,
 * transfer mechanism, and data sensitivity.
 *
 * @param transfer The cross-border transfer to assess
 * @returns Risk assessment result with score, factors, and recommendations
 */
export declare function assessTransferRisk(transfer: CrossBorderTransfer): TransferRiskResult;

export declare interface AuditCheck {
    id: string;
    label: string;
    status: AuditCheckStatus;
    detail: string;
}

export declare type AuditCheckStatus = 'pass' | 'warn' | 'fail';

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

/**
 * Represents the data submitted by the breach report form.
 */
export declare interface BreachFormSubmission {
    /** Title/summary of the breach */
    title: string;
    /** Detailed description of the breach */
    description: string;
    /** Breach category identifier */
    category: string;
    /** Timestamp (ms) when the breach was discovered */
    discoveredAt: number;
    /** Timestamp (ms) when the breach occurred (if known) */
    occurredAt?: number;
    /** Timestamp (ms) when the form was submitted */
    reportedAt: number;
    /** Person reporting the breach */
    reporter: {
        name: string;
        email: string;
        department: string;
        phone?: string;
    };
    /** Systems or applications affected by the breach */
    affectedSystems: string[];
    /** Types of data involved in the breach */
    dataTypes: string[];
    /** Estimated number of affected data subjects */
    estimatedAffectedSubjects?: number;
    /**
     * Approximate number of personal data RECORDS concerned. Distinct from
     * subject count (one subject may have many records). NDPA Section 40(2).
     */
    approximateRecordCount?: number;
    /**
     * Categories of data subjects affected (e.g. customers, employees, minors).
     * NDPA Section 40(2).
     */
    dataSubjectCategories?: string[];
    /** Whether sensitive personal data (NDPA Section 30) is involved */
    involvesSensitiveData?: boolean;
    /**
     * Likely consequences of the breach for affected data subjects.
     * Required content for the NDPC report and Section 40(3) communications.
     */
    likelyConsequences?: string;
    /**
     * Measures taken or proposed to mitigate adverse effects.
     * NDPA Section 40(3).
     */
    mitigationMeasures?: string;
    /**
     * Data Protection Officer contact details (Section 32(3)(c) — DPO is the
     * named NDPC contact). Falls back to organisation-level DPO if omitted.
     */
    dpoContact?: {
        name: string;
        email: string;
        phone?: string;
    };
    /**
     * Whether this is a phased / interim report submitted under Section 40(2)
     * before complete information is available.
     */
    isPhasedReport?: boolean;
    /** ID of the prior phased report this report supplements, if any. */
    supplementsReportId?: string;
    /** Current status of the breach */
    status: 'ongoing' | 'contained' | 'resolved';
    /** Initial actions taken to address the breach */
    initialActions?: string;
    /** File attachments included with the report */
    attachments: Array<{
        name: string;
        type: string;
        size: number;
        file: File;
    }>;
}

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

/**
 * Breach notification management component. Implements NDPA Section 40 requirements for
 * managing breach notifications, tracking 72-hour NDPC reporting deadlines, and coordinating
 * data subject notifications.
 */
export declare const BreachNotificationManager: React__default.FC<BreachNotificationManagerProps>;

export declare interface BreachNotificationManagerClassNames {
    root?: string;
    header?: string;
    title?: string;
    breachList?: string;
    breachItem?: string;
    statusBadge?: string;
    timeline?: string;
    timelineStep?: string;
    detailPanel?: string;
}

export declare interface BreachNotificationManagerProps {
    /**
     * List of breach reports to manage
     */
    breachReports: BreachReport[];
    /**
     * List of risk assessments
     */
    riskAssessments: RiskAssessment[];
    /**
     * List of regulatory notifications
     */
    regulatoryNotifications: RegulatoryNotification[];
    /**
     * Callback function called when a breach is selected
     */
    onSelectBreach?: (breachId: string) => void;
    /**
     * Callback function called when a risk assessment is requested
     */
    onRequestAssessment?: (breachId: string) => void;
    /**
     * Callback function called when a notification is requested
     */
    onRequestNotification?: (breachId: string) => void;
    /**
     * Title displayed on the manager
     * @default "Breach Notification Manager"
     */
    title?: string;
    /**
     * Description text displayed on the manager
     * @default "Manage data breach notifications and track compliance with NDPA Section 40 requirements."
     */
    description?: string;
    /**
     * Custom CSS class for the manager
     */
    className?: string;
    /**
     * Custom CSS class for the buttons
     */
    buttonClassName?: string;
    /**
     * Override class names for individual elements
     */
    classNames?: BreachNotificationManagerClassNames;
    /**
     * Remove all default styles, only applying classNames overrides
     */
    unstyled?: boolean;
    /**
     * Whether to show the breach details
     * @default true
     */
    showBreachDetails?: boolean;
    /**
     * Whether to show the notification timeline
     * @default true
     */
    showNotificationTimeline?: boolean;
    /**
     * Whether to show the deadline alerts
     * @default true
     */
    showDeadlineAlerts?: 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;
    }>;
}

/**
 * Breach report form component. Implements NDPA Section 40 breach notification requirements,
 * enabling organizations to document and report data breaches within the mandated 72-hour window.
 */
export declare const BreachReportForm: React__default.FC<BreachReportFormProps>;

export declare interface BreachReportFormClassNames {
    root?: string;
    title?: string;
    form?: string;
    fieldGroup?: string;
    label?: string;
    input?: string;
    select?: string;
    textarea?: string;
    submitButton?: string;
    /** Alias for submitButton */
    primaryButton?: string;
    notice?: string;
    /** Custom class applied when isSubmitting is true (e.g. a loading overlay) */
    loadingOverlay?: string;
    /** Live NDPC-notification completeness panel */
    completeness?: string;
}

export declare interface BreachReportFormProps {
    /**
     * Available breach categories
     */
    categories: BreachCategory[];
    /**
     * Callback function called when form is submitted
     */
    onSubmit: (data: BreachFormSubmission) => void;
    /**
     * Callback function called when form validation fails
     */
    onValidationError?: (errors: Record<string, string>) => void;
    /**
     * Title displayed on the form
     * @default "Report a Data Breach"
     */
    title?: string;
    /**
     * Description text displayed on the form.
     *
     * @default "Use this form to report a suspected or confirmed data breach in accordance with NDPA Section 40. All fields marked with * are required."
     */
    description?: string;
    /**
     * Text for the submit button
     * @default "Submit Report"
     */
    submitButtonText?: string;
    /**
     * Custom CSS class for the form
     */
    className?: string;
    /**
     * Custom CSS class for the submit button
     */
    buttonClassName?: string;
    /**
     * Override class names for individual elements
     */
    classNames?: BreachReportFormClassNames;
    /**
     * Remove all default styles, only applying classNames overrides
     */
    unstyled?: boolean;
    /**
     * Whether the form is currently submitting.
     * When true, the submit button is disabled and shows "Submitting..." text.
     */
    isSubmitting?: boolean;
    /**
     * Whether to show a confirmation message after submission
     * @default true
     */
    showConfirmation?: boolean;
    /**
     * Confirmation message to display after submission
     * @default "Your breach report has been submitted successfully. The data protection team has been notified."
     */
    confirmationMessage?: string;
    /**
     * Whether to allow file attachments
     * @default true
     */
    allowAttachments?: boolean;
    /**
     * Maximum number of attachments allowed
     * @default 5
     */
    maxAttachments?: number;
    /**
     * Maximum file size for attachments (in bytes)
     * @default 5242880 (5MB)
     */
    maxFileSize?: number;
    /**
     * Allowed file types for attachments
     * @default ['.pdf', '.jpg', '.jpeg', '.png', '.doc', '.docx', '.xls', '.xlsx', '.txt']
     */
    allowedFileTypes?: string[];
    /**
     * Default values to pre-fill form fields.
     * Useful for editing existing breach reports or pre-populating known data.
     */
    defaultValues?: Partial<BreachFormSubmission>;
    /**
     * Callback fired when the form is reset via the Reset button.
     * To fully remount the component (clearing all internal state),
     * change the `key` prop from the parent.
     */
    onReset?: () => void;
    /**
     * Show a live NDPC-notification readiness panel that scores the form against
     * the NDPA S. 40 / GAID 2025 Article 33 mandated content and the 72-hour
     * deadline as the user fills it in.
     * @default true
     */
    showCompleteness?: boolean;
}

/**
 * Breach risk assessment component. Implements NDPA Section 40 requirements for assessing
 * breach severity and determining whether NDPC notification is required within 72 hours.
 */
export declare const BreachRiskAssessment: React__default.FC<BreachRiskAssessmentProps>;

export declare interface BreachRiskAssessmentClassNames {
    root?: string;
    header?: string;
    title?: string;
    slider?: string;
    riskBadge?: string;
    riskScore?: string;
    notificationStatus?: string;
    submitButton?: string;
    /** Alias for submitButton */
    primaryButton?: string;
}

export declare interface BreachRiskAssessmentProps {
    /**
     * The breach data to assess
     */
    breachData: BreachReport;
    /**
     * Initial assessment data (if editing an existing assessment)
     */
    initialAssessment?: Partial<RiskAssessment>;
    /**
     * Callback function called when assessment is completed
     */
    onComplete: (assessment: RiskAssessment) => void;
    /**
     * Title displayed on the assessment form
     * @default "Breach Risk Assessment"
     */
    title?: string;
    /**
     * Description text displayed on the assessment form
     * @default "Assess the risk level of this data breach to determine notification requirements under NDPA Section 40."
     */
    description?: string;
    /**
     * Text for the submit button
     * @default "Complete Assessment"
     */
    submitButtonText?: string;
    /**
     * Custom CSS class for the form
     */
    className?: string;
    /**
     * Custom CSS class for the submit button
     */
    buttonClassName?: string;
    /**
     * Override class names for individual elements
     */
    classNames?: BreachRiskAssessmentClassNames;
    /**
     * Remove all default styles, only applying classNames overrides
     */
    unstyled?: boolean;
    /**
     * Whether to show the breach summary
     * @default true
     */
    showBreachSummary?: boolean;
    /**
     * Whether to show notification requirements after assessment
     * @default true
     */
    showNotificationRequirements?: boolean;
}

/**
 * Calculates the severity of a data breach based on various factors
 * @param report The breach report
 * @param assessment The risk assessment (if available)
 * @returns The calculated severity and notification requirements
 */
export declare function calculateBreachSeverity(report: BreachReport, assessment?: RiskAssessment): {
    severityLevel: 'low' | 'medium' | 'high' | 'critical';
    notificationRequired: boolean;
    urgentNotificationRequired: boolean;
    timeframeHours: number;
    justification: string;
};

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

/**
 * Classify an organisation's DCPMI status, registration tier, annual fee, and
 * Compliance Audit Returns obligations under NDPC GAID 2025.
 */
export declare function classifyDCPMI(input: DCPMIInput, options?: DCPMIClassificationOptions): DCPMIClassification;

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.
 */
export 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[];
}

export declare interface ConsentAnalyticsEvent {
    action: 'shown' | 'accepted_all' | 'rejected_all' | 'customized' | 'dismissed';
    timestamp: number;
    version: string;
    categories?: Record<string, boolean>;
}

/**
 * Represents a single entry in the consent audit trail.
 * Each entry captures what happened, when, and the full consent state
 * at that point in time, satisfying NDPA recordkeeping requirements.
 */
export declare interface ConsentAuditEntry {
    /** The type of consent action that occurred */
    action: 'consent_given' | 'consent_withdrawn' | 'consent_updated' | 'consent_expired';
    /** Unix timestamp (ms) when the action occurred */
    timestamp: number;
    /** Version of the consent form at the time of the action */
    version: string;
    /** Full snapshot of consent category states */
    categories: Record<string, boolean>;
    /** How consent was collected (e.g. "banner", "customize", "api") */
    method: string;
    /** Browser user-agent string for forensic traceability */
    userAgent?: string;
}

/**
 * Consent banner component. Implements NDPA Sections 25-26 consent requirements
 * for obtaining and managing data subject consent.
 */
export declare const ConsentBanner: React__default.FC<ConsentBannerProps>;

export declare interface ConsentBannerClassNames {
    root?: string;
    container?: string;
    title?: string;
    description?: string;
    optionsList?: string;
    optionItem?: string;
    optionCheckbox?: string;
    optionLabel?: string;
    optionDescription?: string;
    buttonGroup?: string;
    acceptButton?: string;
    rejectButton?: string;
    customizeButton?: string;
    saveButton?: string;
    customizePanel?: string;
    selectAllButton?: string;
    /** The optional on-page cookie scan panel (shown in the customize view) */
    cookieScanPanel?: string;
    /** Alias for acceptButton */
    primaryButton?: string;
    /** Alias for rejectButton */
    secondaryButton?: string;
}

export declare interface ConsentBannerProps {
    /**
     * Array of consent options to display
     */
    options: ConsentOption[];
    /**
     * Callback function called when user saves their consent choices
     */
    onSave: (settings: ConsentSettings) => void;
    /**
     * Title displayed on the banner
     * @default "We Value Your Privacy"
     */
    title?: string;
    /**
     * Description text displayed on the banner
     * @default "We use cookies and similar technologies to provide our services and enhance your experience. Your consent is collected in accordance with NDPA Sections 25-26."
     */
    description?: string;
    /**
     * Text for the accept all button
     * @default "Accept All"
     */
    acceptAllButtonText?: string;
    /**
     * Text for the reject all button
     * @default "Reject All"
     */
    rejectAllButtonText?: string;
    /**
     * Text for the customize button
     * @default "Customize"
     */
    customizeButtonText?: string;
    /**
     * Text for the save button
     * @default "Save Preferences"
     */
    saveButtonText?: string;
    /**
     * Position of the banner.
     * 'top', 'bottom', and 'center' render via a portal to document.body
     * with fixed positioning so the banner overlays the page.
     * 'inline' renders in the normal DOM tree without a portal.
     * @default "bottom"
     */
    position?: 'top' | 'bottom' | 'center' | 'inline';
    /**
     * Visual treatment.
     * - 'bar'   (default): full-width strip pinned to the edge.
     * - 'card'  : bounded floating card with rounded corners and a margin
     *             from the screen edges. Pairs well with `position="bottom"`.
     * - 'modal' : centered card with a backdrop overlay. Forces center
     *             placement regardless of `position`.
     * @default "bar"
     */
    variant?: 'bar' | 'card' | 'modal';
    /**
     * z-index applied to the fixed-position banner.
     * Ignored when position is 'inline'.
     * @default 9999
     */
    zIndex?: number;
    /**
     * Version of the consent form
     * @default "1.0"
     */
    version?: string;
    /**
     * Whether to show the banner
     * If not provided, the banner will be shown if no consent has been saved
     */
    show?: boolean;
    /**
     * Storage key for consent settings
     * @default "ndpr_consent"
     */
    storageKey?: string;
    /**
     * Whether the banner manages its own localStorage persistence.
     * Set to false when an external storage mechanism (e.g., ConsentStorage)
     * is responsible for persisting consent settings under the same key.
     * This avoids race conditions where two writers target the same storage key.
     * @default true
     */
    manageStorage?: boolean;
    /**
     * Custom CSS class for the banner
     */
    className?: string;
    /**
     * Custom CSS class for the buttons
     */
    buttonClassName?: string;
    /**
     * Custom CSS class for the primary button
     */
    primaryButtonClassName?: string;
    /**
     * Custom CSS class for the secondary button
     */
    secondaryButtonClassName?: string;
    /**
     * Object of CSS class overrides keyed by semantic section name.
     * Takes priority over buttonClassName / primaryButtonClassName / secondaryButtonClassName.
     */
    classNames?: ConsentBannerClassNames;
    /**
     * When true, all default Tailwind classes are removed so consumers
     * can style from scratch using classNames.
     */
    unstyled?: boolean;
    /**
     * Optional analytics callback fired on each user interaction.
     * Called when the banner is shown, accepted, rejected, customized, or dismissed.
     */
    onAnalytics?: (event: ConsentAnalyticsEvent) => void;
    /**
     * Show a "cookies on this page" scan panel inside the customize view. It
     * audits the cookies actually present against `declaredCookies` and flags
     * undeclared ones — a transparency / self-audit aid (NDPA S.25-26 specific,
     * informed consent). Off by default.
     * @default false
     */
    showCookieScan?: boolean;
    /**
     * The cookies you declare, matched against what's present when
     * `showCookieScan` is on. Without it, every present cookie is treated as
     * undeclared (though the built-in registry may still identify it).
     */
    declaredCookies?: DeclaredCookie[];
    /**
     * Options forwarded to the scan (e.g. `knownCookies`, `useKnownRegistry`,
     * or a `cookieString` to scan instead of `document.cookie`).
     */
    cookieScanOptions?: CookieScanOptions;
    /**
     * Heading for the cookie scan panel.
     * @default "Cookies on this page"
     */
    cookieScanTitle?: string;
}

/**
 * Consent management component. Implements NDPA Sections 25-26 consent requirements,
 * allowing data subjects to review and update their consent preferences.
 */
export declare const ConsentManager: React__default.FC<ConsentManagerProps>;

export declare interface ConsentManagerClassNames {
    root?: string;
    header?: string;
    title?: string;
    description?: string;
    optionsList?: string;
    optionItem?: string;
    toggle?: string;
    saveButton?: string;
    resetButton?: string;
    /** Alias for saveButton */
    primaryButton?: string;
    /** Alias for resetButton */
    secondaryButton?: string;
}

export declare interface ConsentManagerProps {
    /**
     * Array of consent options to display
     */
    options: ConsentOption[];
    /**
     * Current consent settings
     */
    settings?: ConsentSettings;
    /**
     * Callback function called when user saves their consent choices
     */
    onSave: (settings: ConsentSettings) => void;
    /**
     * Title displayed in the manager
     * @default "Manage Your Privacy Settings"
     */
    title?: string;
    /**
     * Description text displayed in the manager
     * @default "Update your consent preferences at any time. Required cookies cannot be disabled as they are necessary for the website to function. Consent management is provided in accordance with NDPA Sections 25-26."
     */
    description?: string;
    /**
     * Text for the save button
     * @default "Save Preferences"
     */
    saveButtonText?: string;
    /**
     * Text for the reset button
     * @default "Reset to Defaults"
     */
    resetButtonText?: string;
    /**
     * Version of the consent form
     * @default "1.0"
     */
    version?: string;
    /**
     * Custom CSS class for the manager
     */
    className?: string;
    /**
     * Custom CSS class for the buttons
     */
    buttonClassName?: string;
    /**
     * Custom CSS class for the primary button
     */
    primaryButtonClassName?: string;
    /**
     * Custom CSS class for the secondary button
     */
    secondaryButtonClassName?: string;
    /**
     * Object of CSS class overrides keyed by semantic section name.
     * Takes priority over buttonClassName / primaryButtonClassName / secondaryButtonClassName.
     */
    classNames?: ConsentManagerClassNames;
    /**
     * When true, all default Tailwind classes are removed so consumers
     * can style from scratch using classNames.
     */
    unstyled?: boolean;
    /**
     * Whether to show a success message after saving
     * @default true
     */
    showSuccessMessage?: boolean;
    /**
     * Success message to display after saving
     * @default "Your preferences have been saved."
     */
    successMessage?: string;
    /**
     * Duration to show the success message (in milliseconds)
     * @default 3000
     */
    successMessageDuration?: number;
}

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

export declare const ConsentStorage: ({ settings, storageOptions, onLoad, onSave, autoSave, autoLoad, classNames, unstyled, children }: ConsentStorageProps) => React__default.ReactElement | null;

export declare interface ConsentStorageClassNames {
    root?: string;
}

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

export declare interface ConsentStorageProps {
    /**
     * Current consent settings
     */
    settings: ConsentSettings;
    /**
     * Storage options for consent settings
     */
    storageOptions?: ConsentStorageOptions;
    /**
     * Callback function called when settings are loaded from storage
     */
    onLoad?: (settings: ConsentSettings | null) => void;
    /**
     * Callback function called when settings are saved to storage
     */
    onSave?: (settings: ConsentSettings) => void;
    /**
     * Whether to automatically save settings to storage
     * @default true
     */
    autoSave?: boolean;
    /**
     * Whether to automatically load settings from storage on mount
     * @default true
     */
    autoLoad?: boolean;
    /**
     * Object of CSS class overrides keyed by semantic section name.
     */
    classNames?: ConsentStorageClassNames;
    /**
     * When true, all default classes are removed so consumers
     * can style from scratch using classNames.
     */
    unstyled?: boolean;
    /**
     * Children to render
     * Can be either React nodes or a render prop function that receives storage methods
     */
    children?: React__default.ReactNode | ((props: {
        loadSettings: () => ConsentSettings | null;
        saveSettings: (settings: ConsentSettings) => void;
        clearSettings: () => void;
        loaded: boolean;
    }) => React__default.ReactNode);
}

export declare interface CookieAdapterOptions {
    domain?: string;
    path?: string;
    expires?: number;
    secure?: boolean;
    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;
}

/**
 * Creates a new audit entry from consent settings. If `previousSettings` is
 * provided, the action is automatically determined by comparing old and new
 * states. Otherwise `action` defaults to `'consent_given'`.
 */
export declare function createAuditEntry(settings: ConsentSettings, previousSettings?: ConsentSettings | null, actionOverride?: ConsentAuditEntry['action']): ConsentAuditEntry;

/**
 * Creates a complete business privacy po