@tantainnovative/ndpr-toolkit/dist/cross-border.d.mts

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

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

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

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

/**
 * Database of country adequacy determinations for cross-border data transfers.
 *
 * This map is keyed by ISO 3166-1 alpha-2 country code (uppercase).
 *
 * IMPORTANT — Statuses with `recognizedBy: 'self-assessment'` are this toolkit's
 * guidance assessments based on each country's data-protection framework. They
 * are NOT NDPC-issued adequacy decisions. NDPC has not (as of publication)
 * published any formal Section 42 adequacy list. Organisations transferring
 * personal data outside Nigeria should perform their own transfer impact
 * assessment and consult counsel before relying on any entry here.
 */
export declare const COUNTRY_ADEQUACY_MAP: Record<string, CountryAdequacy>;

/**
 * Represents a country's adequacy determination for cross-border data transfers.
 */
export declare interface CountryAdequacy {
    /** Full country name */
    country: string;
    /** ISO 3166-1 alpha-2 country code */
    isoCode: string;
    /** Adequacy status for data protection purposes */
    adequacyStatus: CountryAdequacyStatus;
    /**
     * Source of the adequacy determination.
     * - 'NDPC' — formally listed by the Nigeria Data Protection Commission under
     *   NDPA Section 42 (no such list has been published at time of writing).
     * - 'EU' — recognized as adequate by EU member-state membership / GDPR.
     * - 'UK' — recognized by the UK ICO.
     * - 'self-assessment' — toolkit maintainers' guidance assessment. Verify
     *   independently and confirm with your DPO/counsel before relying on it.
     */
    recognizedBy: 'NDPC' | 'EU' | 'UK' | 'self-assessment';
    /** Additional notes about the adequacy determination */
    notes: string;
    /** Date the adequacy determination was last reviewed */
    lastUpdated: string;
}

/**
 * Country adequacy determinations for cross-border data transfers
 * under the Nigeria Data Protection Act (NDPA).
 *
 * IMPORTANT — Not legal advice and not an NDPC adequacy list.
 *
 * As of publication, the Nigeria Data Protection Commission has not published
 * a formal list of countries it deems adequate under NDPA Section 42. The
 * Commission is empowered to issue such guidelines under Section 42(3), but
 * has not yet done so. The entries in this map are *self-assessments* by the
 * toolkit maintainers based on each country's data-protection framework, and
 * are intended for guidance only. Verify the current NDPC position and consult
 * counsel before relying on any entry here for a transfer impact assessment.
 */
/**
 * Adequacy status of a country for cross-border data transfers.
 */
export declare type CountryAdequacyStatus = 'adequate' | 'partially_adequate' | 'not_adequate' | 'pending';

export declare const CrossBorder: {
    Provider: React_2.FC<CrossBorderProviderProps>;
    Manager: React_2.FC<CrossBorderTransferManagerProps>;
};

declare type CrossBorderContextValue = UseCrossBorderTransferReturn;

export declare const CrossBorderProvider: React__default.FC<CrossBorderProviderProps>;

export declare interface CrossBorderProviderProps {
    adapter?: StorageAdapter<CrossBorderTransfer[]>;
    storageKey?: string;
    useLocalStorage?: boolean;
    initialTransfers?: CrossBorderTransfer[];
    onAdd?: (transfer: CrossBorderTransfer) => void;
    onUpdate?: (transfer: CrossBorderTransfer) => void;
    onRemove?: (id: string) => void;
    children: React__default.ReactNode;
}

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

/**
 * Cross-border data transfer management component. Implements NDPA Sections 41-43 requirements
 * for managing international data transfers, including adequacy decisions, standard contractual
 * clauses, and NDPC authorization.
 */
export declare const CrossBorderTransferManager: React__default.FC<CrossBorderTransferManagerProps>;

declare interface CrossBorderTransferManagerClassNames {
    root?: string;
    header?: string;
    title?: string;
    summary?: string;
    summaryCard?: string;
    transferList?: string;
    transferItem?: string;
    form?: string;
    input?: string;
    select?: string;
    submitButton?: string;
    /** Alias for submitButton */
    primaryButton?: string;
    riskBadge?: string;
    statusBadge?: string;
    detailPanel?: string;
    approvalStatus?: string;
}

declare interface CrossBorderTransferManagerProps {
    /**
     * List of cross-border transfers to display
     */
    transfers: CrossBorderTransfer[];
    /**
     * Callback when a new transfer is added.
     */
    onAdd?: (transfer: Omit<CrossBorderTransfer, 'id' | 'createdAt' | 'updatedAt'>) => void;
    /**
     * Callback when a transfer is updated.
     */
    onUpdate?: (id: string, updates: Partial<CrossBorderTransfer>) => void;
    /**
     * Callback when a transfer is archived. NDPA preference is soft-delete
     * over hard-delete; consumers should treat this as an archive signal.
     */
    onArchive?: (id: string) => void;
    /**
     * Compliance summary data
     */
    summary?: CrossBorderSummary;
    /**
     * Title displayed on the manager
     * @default "Cross-Border Data Transfer Manager"
     */
    title?: string;
    /**
     * Description text displayed on the manager
     * @default "Manage and document cross-border personal data transfers in compliance with NDPA 2023 Part VIII (Sections 41-43)."
     */
    description?: string;
    /**
     * Custom CSS class for the manager container
     */
    className?: string;
    /**
     * Custom CSS class for buttons
     */
    buttonClassName?: string;
    /**
     * Whether to show the compliance summary section
     * @default true
     */
    showSummary?: boolean;
    /**
     * Whether to show the TIA section in the form
     * @default true
     */
    showTIA?: boolean;
    /**
     * Override class names for individual sections of the component.
     * Takes priority over className / buttonClassName.
     */
    classNames?: CrossBorderTransferManagerClassNames;
    /**
     * When true, all default styling is removed so consumers
     * can style from scratch using classNames.
     */
    unstyled?: boolean;
}

/**
 * Returns all countries that are considered adequate for cross-border data transfers.
 *
 * @returns Array of CountryAdequacy entries with adequacyStatus === 'adequate'
 */
export declare function getAdequateCountries(): CountryAdequacy[];

/**
 * Look up the adequacy determination for a country by name or ISO code.
 *
 * The search is case-insensitive and matches against both the `country` field
 * and the `isoCode` field.
 *
 * @param countryOrCode A country name (e.g. "Germany") or ISO 3166-1 alpha-2 code (e.g. "DE")
 * @returns The matching CountryAdequacy entry, or undefined if not found
 */
export declare function getCountryAdequacy(countryOrCode: string): CountryAdequacy | undefined;

/**
 * Returns a human-readable description of a transfer mechanism with its NDPA section reference.
 *
 * @param mechanism The transfer mechanism
 * @returns Description including the relevant NDPA section
 */
export declare function getTransferMechanismDescription(mechanism: TransferMechanism): string;

/**
 * Returns whether NDPC approval is required for a given transfer mechanism.
 * Under NDPA Section 42(5), the Commission may approve binding corporate rules,
 * codes of conduct, certification mechanisms, or similar instruments. Standard
 * contractual clauses are one of the appropriate safeguards under Section 41(1)(a)
 * and the Commission may approve them per Section 42(4).
 *
 * @param mechanism The transfer mechanism
 * @returns Whether NDPC approval is typically required
 */
export declare function isNDPCApprovalRequired(mechanism: TransferMechanism): boolean;

/**
 * Determines whether a transfer to the specified country requires NDPC approval.
 *
 * Countries that are not in the adequacy database or that have a status other
 * than 'adequate' require NDPC approval (or an alternative transfer mechanism
 * such as standard contractual clauses or binding corporate rules).
 *
 * @param countryOrCode A country name or ISO 3166-1 alpha-2 code
 * @returns true if NDPC approval is likely required for transfers to this country
 */
export declare function requiresNDPCApproval(countryOrCode: string): boolean;

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

/**
 * Transfer Impact Assessment (TIA) for cross-border transfers
 */
export declare interface TransferImpactAssessment {
    /** Unique identifier */
    id: string;
    /** ID of the associated cross-border transfer */
    transferId: string;
    /** Date the assessment was conducted */
    assessmentDate: number;
    /** Person who conducted the assessment */
    assessor: {
        name: string;
        role: string;
        email: string;
    };
    /** Analysis of the destination country's legal framework */
    destinationLegalFramework: string;
    /** Whether the destination has data protection legislation */
    hasDataProtectionLaw: boolean;
    /** Whether the destination has an independent supervisory authority */
    hasIndependentAuthority: boolean;
    /** Risk of government access to the data */
    governmentAccessRisk: 'low' | 'medium' | 'high';
    /** Overall assessment of data protection level */
    dataProtectionLevel: 'adequate' | 'partially_adequate' | 'inadequate';
    /** Supplementary measures to address gaps */
    supplementaryMeasures: string[];
    /** Technical measures (encryption, pseudonymization, etc.) */
    technicalMeasures: string[];
    /** Contractual measures */
    contractualMeasures: string[];
    /** Organizational measures */
    organizationalMeasures: string[];
    /** Overall conclusion */
    conclusion: string;
    /** Whether the transfer can proceed based on the assessment */
    approved: boolean;
    /** Conditions for the transfer (if approved with conditions) */
    conditions?: string[];
}

/**
 * Cross-Border Data Transfer types aligned with NDPA 2023 Part VIII (Sections 41-43).
 * Personal data may only be transferred outside Nigeria under the bases listed in
 * Section 41(1), where Section 42 defines adequacy and Section 43 lists derogations.
 *
 * Note: These are guidance labels — not legal advice. Verify with your DPO or counsel.
 */
/**
 * Transfer mechanisms recognized under the NDPA
 */
export declare type TransferMechanism = 'adequacy_decision' | 'standard_clauses' | 'binding_corporate_rules' | 'ndpc_authorization' | 'explicit_consent' | 'contract_performance' | 'public_interest' | 'legal_claims' | 'vital_interests';

/**
 * Risk assessment result for a cross-border transfer
 */
export declare interface TransferRiskResult {
    riskLevel: 'low' | 'medium' | 'high';
    riskScore: number;
    factors: string[];
    recommendations: string[];
}

/**
 * Validation result for a cross-border transfer
 */
export declare interface TransferValidationResult {
    isValid: boolean;
    errors: string[];
    warnings: string[];
}

export declare function useCrossBorderCompound(): CrossBorderContextValue;

/**
 * Hook for managing cross-border data transfers in compliance with NDPA Part VIII (Sections 41-43).
 *
 * @example
 * ```tsx
 * import { useCrossBorderTransfer } from '@tantainnovative/ndpr-toolkit/hooks';
 *
 * function TransferRegister() {
 *   const { transfers, getSummary } = useCrossBorderTransfer();
 *   const summary = getSummary();
 *   return <p>{summary.totalActiveTransfers} active cross-border transfers.</p>;
 * }
 * ```
 */
export declare function useCrossBorderTransfer({ initialTransfers, adapter, storageKey, useLocalStorage, onAdd, onUpdate, onRemove, }?: UseCrossBorderTransferOptions): UseCrossBorderTransferReturn;

declare interface UseCrossBorderTransferOptions {
    /**
     * Initial transfers to load
     */
    initialTransfers?: CrossBorderTransfer[];
    /**
     * Pluggable storage adapter. When provided, takes precedence over storageKey/useLocalStorage.
     */
    adapter?: StorageAdapter<CrossBorderTransfer[]>;
    /**
     * Storage key for transfer data
     * @default "ndpr_cross_border_transfers"
     * @deprecated Use adapter instead
     */
    storageKey?: string;
    /**
     * Whether to use local storage to persist transfers
     * @default true
     * @deprecated Use adapter instead
     */
    useLocalStorage?: boolean;
    /**
     * Callback function called when a transfer is added
     */
    onAdd?: (transfer: CrossBorderTransfer) => void;
    /**
     * Callback function called when a transfer is updated
     */
    onUpdate?: (transfer: CrossBorderTransfer) => void;
    /**
     * Callback function called when a transfer is removed
     */
    onRemove?: (id: string) => void;
}

export declare interface UseCrossBorderTransferReturn {
    /**
     * All cross-border transfers
     */
    transfers: CrossBorderTransfer[];
    /**
     * Add a new cross-border transfer
     */
    addTransfer: (transfer: Omit<CrossBorderTransfer, 'id' | 'createdAt' | 'updatedAt'>) => CrossBorderTransfer;
    /**
     * Update an existing cross-border transfer
     */
    updateTransfer: (id: string, updates: Partial<CrossBorderTransfer>) => CrossBorderTransfer | null;
    /**
     * Remove a cross-border transfer
     */
    removeTransfer: (id: string) => void;
    /**
     * Get a cross-border transfer by ID
     */
    getTransfer: (id: string) => CrossBorderTransfer | null;
    /**
     * Get a compliance summary of all cross-border transfers
     */
    getSummary: () => CrossBorderSummary;
    /**
     * Validate a cross-border transfer
     */
    validateTransfer: (transfer: CrossBorderTransfer) => TransferValidationResult;
    /**
     * Whether the adapter is still loading data (relevant for async adapters)
     */
    isLoading: boolean;
}

/**
 * Validates a cross-border transfer record for completeness and compliance.
 * Checks required fields, verifies that NDPC approval is documented when required,
 * and ensures safeguards are in place.
 *
 * @param transfer The cross-border transfer to validate
 * @returns Validation result with errors and warnings
 */
export declare function validateTransfer(transfer: CrossBorderTransfer): TransferValidationResult;

export { }