/**
 * Privacy Data Protection (PDP) Module
 *
 * Indonesian PII scanning and anonymization utilities for
 * compliance with UU PDP (Pelindungan Data Pribadi).
 *
 * @module PDP
 */
/**
 * Supported PII (Personally Identifiable Information) types
 * for Indonesian data.
 *
 * @example
 * ```typescript
 * const piiType: PIIType = 'nik';
 * ```
 *
 * @public
 */
type PIIType = 'nik' | 'npwp' | 'phone' | 'email' | 'passport' | 'bpjs' | 'bank-account';
/**
 * Confidence level for PII detection.
 *
 * - `high`: Valid format + checksum/validation passed
 * - `medium`: Valid format + prefix matched
 * - `low`: Pattern match only (no validation)
 *
 * @public
 */
type PIIConfidence = 'high' | 'medium' | 'low';
/**
 * Result of a PII scan operation.
 *
 * Contains information about a detected PII element including
 * its type, value, position in the text, and detection confidence.
 *
 * @public
 */
interface PIIFinding {
    /**
     * The type of PII detected.
     */
    type: PIIType;
    /**
     * The actual PII value that was detected.
     */
    value: string;
    /**
     * Start index of the PII in the original text (0-based).
     */
    startIndex: number;
    /**
     * End index of the PII in the original text (exclusive).
     */
    endIndex: number;
    /**
     * Confidence level of the detection.
     */
    confidence: PIIConfidence;
}
/**
 * Options for PII scanning and masking operations.
 *
 * @public
 */
interface PIIOptions {
    /**
     * Explicit keys to mask in objects (supports strings and RegExp).
     * If provided, these keys will be masked regardless of autoDetectPII.
     *
     * @example
     * ```typescript
     * { explicitKeys: ['password', 'secret', /^token$/i] }
     * ```
     */
    explicitKeys?: Array<string | RegExp>;
    /**
     * Whether to auto-detect PII in string values.
     * @default true
     */
    autoDetectPII?: boolean;
    /**
     * Character to use for masking.
     * @default '*'
     */
    maskChar?: string;
    /**
     * Masking strategy to use.
     * - `full`: Replace entire value with maskChar
     * - `partial`: Preserve first and last few characters
     *
     * @default 'partial'
     */
    maskStrategy?: 'full' | 'partial';
    /**
     * Optional replacement text instead of maskChar.
     * Example: `[REDACTED_NIK]`
     */
    replacementText?: string;
    /**
     * Whether to escape special characters for JSON-safe logging.
     * Escapes: \n → \\n, \t → \\t, " → \"
     *
     * @default false
     */
    escapeForLog?: boolean;
}

/**
 * Scans text for Personally Identifiable Information (PII).
 *
 * Detects Indonesian-specific PII types:
 * - NIK (National ID number)
 * - NPWP (Tax ID number)
 * - Phone numbers (Indonesian format)
 * - Email addresses
 * - Passport numbers
 * - BPJS ID numbers
 * - Bank account numbers
 *
 * @param text - Text to scan for PII
 * @returns Array of PII findings with type, value, position, and confidence
 *
 * @example
 * ```typescript
 * const text = "NIK saya 3271054108750001, email budi@email.com";
 * const findings = scanPII(text);
 * // [{ type: 'nik', value: '3271054108750001', startIndex: 10, ... },
 * //  { type: 'email', value: 'budi@email.com', startIndex: 34, ... }]
 * ```
 *
 * @example
 * For data privacy audit:
 * ```typescript
 * const doc = "Kirim ke Jl. Sudirman 45, NIK 3271054108750001";
 * const piiLocations = scanPII(doc);
 * // Use findings to mask/redact before sharing
 * ```
 */
declare function scanPII(text: string): PIIFinding[];

/**
 * Masks PII found in a string using specified mask character.
 *
 * Auto-detects PII types (NIK, NPWP, phone, email, etc.) and
 * replaces them with masked version. Use for logging, display,
 * or data sharing where original values shouldn't be visible.
 *
 * @param text - Text containing PII to mask
 * @param options - Masking options (strategy, char, etc.)
 * @returns Text with PII masked
 *
 * @example
 * ```typescript
 * maskStringPDP("NIK: 3271054108750001");
// "NIK: 3271054108******" (partial mask)
 * ```
 *
 * @example
 * Full mask for logs:
 * ```typescript
 * maskStringPDP("Email: budi@email.com", { maskStrategy: 'full' });
 * // "Email: ***************"
 * ```
 *
 * @example
 * Custom replacement:
 * ```typescript
 * maskStringPDP("Phone: 081234567890", { replacementText: '[REDACTED]' });
 * // "Phone: [REDACTED]"
 * ```
 */
declare function maskStringPDP(text: string, options?: PIIOptions): string;

/**
 * Anonymizes PII in a string by replacing with masked version.
 *
 * Scans text for PII patterns and replaces detected values with
 * masked equivalents. Use for data sharing, logging, or display.
 *
 * @param text - Text containing PII to anonymize
 * @param options - Anonymization options
 * @returns Text with PII replaced (original value not recoverable)
 *
 * @example
 * ```typescript
 * anonymizeString("NIK 3271054108750001");
// "NIK ***************"
 * ```
 *
 * @example
 * For API response sanitization:
 * ```typescript
 * const response = { name: "Budi", nik: "3271054108750001" };
 * const sanitized = anonymizeString(JSON.stringify(response));
 * // Useful before logging or returning to client
 * ```
 */
declare function anonymizeString(text: string, options?: PIIOptions): string;
/**
 * Recursively anonymizes PII in an object or array.
 *
 * Deep-scans nested structures (objects, arrays) for string values
 * containing PII and replaces them with masked version. Handles
 * circular references and preserves non-PII data types.
 *
 * @param payload - Object, array, or primitive to anonymize
 * @param options - Anonymization options
 * @returns Same structure with PII values replaced
 *
 * @example
 * ```typescript
 * const user = {
 *   name: "Budi",
 *   id: "3271054108750001",
 *   email: "budi@email.com"
 * };
 * anonymizePDP(user);
 * // { name: "Budi", id: "***********", email: "***@***.com" }
 * ```
 *
 * @example
 * For API response sanitization:
 * ```typescript
 * const response = {
 *   data: { name: "Budi", nik: "3271054108750001" },
 *   meta: { timestamp: "2024-01-01" }
 * };
 * anonymizePDP(response);
 * // Only string values with PII are masked, meta preserved
 * ```
 */
declare function anonymizePDP<T>(payload: T, options?: PIIOptions): T;

export { type PIIConfidence, type PIIFinding, type PIIOptions, type PIIType, anonymizePDP, anonymizeString, maskStringPDP, scanPII };