@danielarndt0/cnpj-db-loader 2.2.0

package/dist/index.d.ts

@@ -0,0 +1,969 @@
+declare class AppError extends Error {
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(message: string, code?: string, details?: unknown);
+}
+
+declare class ServiceError extends AppError {
+    constructor(message: string, details?: unknown);
+}
+
+declare class ValidationError extends AppError {
+    constructor(message: string, details?: unknown);
+}
+
+type AppEnvironment = "development" | "test" | "production";
+type AppConfig = {
+    appName: string;
+    version: string;
+    environment: AppEnvironment;
+    description: string;
+};
+type DatasetBlock = "companies" | "establishments" | "partners" | "simples_options" | "countries" | "cities" | "partner_qualifications" | "legal_natures" | "cnaes";
+type DatabaseConfig = {
+    defaultDbUrl?: string;
+};
+
+type Result<T> = {
+    ok: true;
+    data: T;
+};
+type Failure = {
+    ok: false;
+    error: string;
+};
+
+declare function ensureDirectory(filePath: string): Promise<void>;
+declare function safeReadText(filePath: string): Promise<string | undefined>;
+declare function safeWriteText(filePath: string, content: string): Promise<void>;
+
+declare function prettyJson(value: unknown): string;
+
+declare function toTitleCase(value: string): string;
+
+declare function defaultExtractedOutputPath(inputPath: string): string;
+
+type SupportedOs = "windows" | "macos" | "linux" | "unknown";
+declare function detectOs(): SupportedOs;
+
+declare function readDatabaseConfig(): Promise<DatabaseConfig>;
+declare function writeDatabaseConfig(config: DatabaseConfig): Promise<void>;
+declare function assertPostgresUrl(url: string): void;
+declare function setDefaultDbUrl(url: string): Promise<void>;
+declare function resetDefaultDbUrl(): Promise<void>;
+
+type FieldDefinition = {
+    sourceLabel: string;
+    columnName: string;
+    dataType: "text" | "integer" | "numeric" | "date" | "boolean";
+    nullable?: boolean;
+    notes?: string;
+};
+type TableLayout = {
+    key: string;
+    tableName: string;
+    sourceName: string;
+    description: string;
+    fields: FieldDefinition[];
+};
+
+type DatasetType = "companies" | "establishments" | "partners" | "simples_options" | "countries" | "cities" | "partner_qualifications" | "legal_natures" | "cnaes" | "reasons" | "zip-archive" | "unknown";
+type InputDetectionMode = "zip-archives-only" | "extracted-tree" | "mixed" | "empty";
+type FileInspection = {
+    relativePath: string;
+    entryName: string;
+    entryKind: "file" | "directory";
+    size: number;
+    inferredType: DatasetType;
+    requiresExtraction: boolean;
+};
+type InspectSummary = {
+    inputPath: string;
+    detectedInputMode: InputDetectionMode;
+    totalEntries: number;
+    zipArchivesFound: number;
+    extractedEntriesFound: number;
+    recognizedByType: Record<string, number>;
+    recognizedDatasets: Partial<Record<DatasetType, number>>;
+    warnings: string[];
+    nextStep?: string | undefined;
+    entries: FileInspection[];
+};
+declare function inspectFiles(inputPath: string): Promise<InspectSummary>;
+
+type ImportDatasetType = Exclude<DatasetType, "zip-archive" | "unknown">;
+type ImportCheckpointStatus = "pending" | "in_progress" | "completed" | "failed";
+type ImportCheckpointRecord = {
+    dataset: ImportDatasetType;
+    filePath: string;
+    fileSize: number;
+    fileMtime: Date;
+    byteOffset: number;
+    rowsCommitted: number;
+    status: ImportCheckpointStatus;
+    lastError?: string | null;
+};
+type ImportFilePlan = {
+    dataset: ImportDatasetType;
+    absolutePath: string;
+    displayPath: string;
+    fileSize: number;
+    fileMtime: Date;
+    totalRows: number;
+    totalBatches: number;
+    checkpoint?: ImportCheckpointRecord;
+};
+type ImportDatasetPlan = {
+    dataset: ImportDatasetType;
+    files: ImportFilePlan[];
+    totalRows: number;
+    totalBatches: number;
+};
+type ImportPlanStatus = "planned" | "in_progress" | "completed" | "failed" | "cancelled";
+type ImportPhaseStatus = "pending" | "in_progress" | "completed" | "failed";
+type ImportPlanRecord = {
+    id: number;
+    sourceFingerprint: string;
+    inputPath: string;
+    validatedPath: string;
+    batchSize: number;
+    targetDatabase: string;
+    totalDatasets: number;
+    totalFiles: number;
+    totalRows: number;
+    totalBatches: number;
+    executionOrder: ImportDatasetType[];
+    status: ImportPlanStatus;
+    loadStatus: ImportPhaseStatus;
+    materializationStatus: ImportPhaseStatus;
+    lastPhase: string | null;
+    lastError: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+    lastUsedAt: Date;
+};
+type ImportSchemaCapabilities = {
+    includeEstablishmentCnpjFullInInsert: boolean;
+    includePartnerDedupeKeyInInsert: boolean;
+    requiresLookupReconciliation: boolean;
+};
+type ImportDatasetPerformanceSummary = {
+    dataset: ImportDatasetType;
+    files: number;
+    plannedRows: number;
+    importedRows: number;
+    plannedBatches: number;
+    committedBatches: number;
+    resumedFiles: number;
+    skippedCompletedFiles: number;
+    retriedRows: number;
+    retriedBatches: number;
+    quarantinedRows: number;
+    scanDurationMs: number;
+    importDurationMs: number;
+    insertDurationMs: number;
+    retryDurationMs: number;
+    quarantineDurationMs: number;
+    materializationDurationMs: number;
+    rowsPerSecond: number;
+    batchesPerMinute: number;
+};
+type ImportPerformanceSummary = {
+    planReused: boolean;
+    totalDurationMs: number;
+    scanDurationMs: number;
+    executionDurationMs: number;
+    lookupLoadDurationMs: number;
+    insertDurationMs: number;
+    retryDurationMs: number;
+    quarantineDurationMs: number;
+    materializationDurationMs: number;
+    rowsPerSecond: number;
+    batchesPerMinute: number;
+    datasets: ImportDatasetPerformanceSummary[];
+};
+type ImportProgressEvent = {
+    kind: "preparing_start";
+    inputPath: string;
+    validatedPath: string;
+    totalDatasets: number;
+    totalFiles: number;
+    batchSize: number;
+    loadBatchSize?: number;
+    materializeBatchSize?: number;
+    targetDatabase: string;
+} | {
+    kind: "preparing_progress";
+    scannedFiles: number;
+    totalFiles: number;
+    countedRows: number;
+    currentFileDisplayPath: string;
+} | {
+    kind: "plan_ready";
+    totalDatasets: number;
+    totalFiles: number;
+    batchSize: number;
+    loadBatchSize?: number;
+    materializeBatchSize?: number;
+    totalRows: number;
+    totalBatches: number;
+    targetDatabase: string;
+    executionOrder: ImportDatasetType[];
+    reused: boolean;
+    planId: number | null;
+} | {
+    kind: "start";
+    inputPath: string;
+    validatedPath: string;
+    totalDatasets: number;
+    totalFiles: number;
+    targetDatabase: string;
+    totalRows: number;
+    totalBatches: number;
+    committedRows: number;
+    committedBatches: number;
+} | {
+    kind: "progress";
+    dataset: ImportDatasetType;
+    datasetIndex: number;
+    totalDatasets: number;
+    currentFilePath: string;
+    currentFileDisplayPath: string;
+    fileIndex: number;
+    completedFiles: number;
+    totalFiles: number;
+    currentFileRowsCommitted: number;
+    currentFileRowsTotal: number;
+    committedRows: number;
+    committedBatches: number;
+    totalBatches: number;
+    currentBatch: number;
+    batchSize: number;
+    checkpointOffset: number;
+    currentFileSize: number;
+    verboseProgress: boolean;
+} | {
+    kind: "materialization_start";
+    totalDatasets: number;
+    datasets: ImportDatasetType[];
+    completedFiles: number;
+    totalFiles: number;
+    processedRows: number;
+    totalRows: number;
+    committedBatches: number;
+    totalBatches: number;
+} | {
+    kind: "materialization_progress";
+    dataset: ImportDatasetType;
+    datasetIndex: number;
+    totalDatasets: number;
+    completedDatasets: number;
+    targetTable: string;
+    stepLabel: string;
+    completedFiles: number;
+    totalFiles: number;
+    processedRows: number;
+    totalRows: number;
+    committedBatches: number;
+    totalBatches: number;
+    elapsedMs?: number;
+    reason?: string;
+    chunkSize?: number;
+    rowsMaterialized?: number;
+    datasetRowCount?: number;
+    chunksCompleted?: number;
+    estimatedChunks?: number;
+    lastStagingId?: number;
+} | {
+    kind: "materialization_finish";
+    totalDatasets: number;
+    completedDatasets: number;
+} | {
+    kind: "finish";
+    totalDatasets: number;
+    totalFiles: number;
+    completedFiles: number;
+    processedRows: number;
+    totalRows: number;
+    committedBatches: number;
+    totalBatches: number;
+    quarantinedRows: number;
+};
+type ImportProgressListener = (event: ImportProgressEvent) => void;
+type ImportOptions = {
+    dbUrl?: string;
+    dataset?: ImportDatasetType | undefined;
+    batchSize?: number | undefined;
+    loadBatchSize?: number | undefined;
+    materializeBatchSize?: number | undefined;
+    verboseProgress?: boolean | undefined;
+    onProgress?: ImportProgressListener | undefined;
+};
+type ImportExecutionMode = "full" | "load" | "materialize";
+type ImportSummary = {
+    executionMode: ImportExecutionMode;
+    inputPath: string;
+    validatedPath: string;
+    targetDatabase: string;
+    importPlanId: number | null;
+    reusedImportPlan: boolean;
+    importedDatasets: ImportDatasetType[];
+    importedFiles: number;
+    processedRows: number;
+    plannedRows: number;
+    committedBatches: number;
+    plannedBatches: number;
+    quarantinedRows: number;
+    resumedFiles: number;
+    skippedCompletedFiles: number;
+    datasetSummaries: Array<{
+        dataset: ImportDatasetType;
+        files: number;
+        rows: number;
+    }>;
+    performance: ImportPerformanceSummary;
+    warnings: string[];
+    progressLogPath: string;
+};
+
+type DatabaseCleanupScope = "staging" | "materialized" | "checkpoints" | "plans";
+type CheckpointCleanupPhase = "load" | "materialization" | "all";
+type DatabaseCleanupSummary = {
+    scope: DatabaseCleanupScope;
+    targetDatabase: string;
+    dataset?: ImportDatasetType | undefined;
+    phase?: CheckpointCleanupPhase | undefined;
+    validatedPath?: string | undefined;
+    planId?: number | undefined;
+    truncatedTables: string[];
+    deletedLoadCheckpoints: number;
+    deletedMaterializationCheckpoints: number;
+    deletedPlans: number;
+    notes: string[];
+};
+
+declare function resolveDatabaseUrl(override?: string): Promise<string>;
+declare function testDatabaseConnection(url: string): Promise<void>;
+declare function cleanupDatabaseStagingData(options?: {
+    dbUrl?: string;
+    dataset?: ImportDatasetType | undefined;
+    validatedPath?: string | undefined;
+}): Promise<DatabaseCleanupSummary>;
+declare function cleanupDatabaseMaterializedData(options?: {
+    dbUrl?: string;
+    dataset?: ImportDatasetType | undefined;
+}): Promise<DatabaseCleanupSummary>;
+declare function cleanupDatabaseCheckpointsData(options?: {
+    dbUrl?: string;
+    phase?: CheckpointCleanupPhase | undefined;
+    dataset?: ImportDatasetType | undefined;
+    validatedPath?: string | undefined;
+    planId?: number | undefined;
+}): Promise<DatabaseCleanupSummary>;
+declare function cleanupDatabasePlansData(options?: {
+    dbUrl?: string;
+    validatedPath?: string | undefined;
+    planId?: number | undefined;
+}): Promise<DatabaseCleanupSummary>;
+declare function resolveDbUrl(override?: string): Promise<string>;
+
+declare function getAllLayouts(): TableLayout[];
+declare function getLayoutSummary(): Array<Pick<TableLayout, "key" | "tableName" | "sourceName">>;
+
+declare function runDoctor(inputPath?: string, dbUrl?: string): Promise<string[]>;
+
+declare const SCHEMA_PROFILES: readonly ["full", "final", "staging"];
+type SchemaProfile = (typeof SCHEMA_PROFILES)[number];
+type SchemaGenerationOptions = {
+    profile?: SchemaProfile;
+};
+
+declare function generateSchemaSql(options?: SchemaGenerationOptions): string;
+declare function writeSchemaFile(outFile: string, options?: SchemaGenerationOptions): Promise<void>;
+declare function resolveSchemaProfile(profile?: string): SchemaProfile;
+
+type ValidationSummary = {
+    ok: boolean;
+    errors: string[];
+    warnings: string[];
+    inspected: InspectSummary;
+    validatedPath: string;
+    presentDatasets: DatasetType[];
+    missingDatasets: DatasetType[];
+    nextStep?: string | undefined;
+};
+declare function validateInputDirectory(inputPath: string): Promise<ValidationSummary>;
+
+type ExtractionEntry = {
+    archivePath: string;
+    archiveName: string;
+    destinationPath: string;
+    success: boolean;
+    sizeInBytes: number;
+    errorMessage?: string;
+};
+type ExtractionSummary = {
+    inputPath: string;
+    outputPath: string;
+    operatingSystem: string;
+    zipFilesFound: number;
+    extractedArchives: string[];
+    skippedEntries: string[];
+    failedArchives: string[];
+    totalArchiveBytes: number;
+    extractedArchiveBytes: number;
+    entries: ExtractionEntry[];
+};
+type ExtractionProgressEvent = {
+    kind: "start";
+    totalArchives: number;
+    totalBytes: number;
+    inputPath: string;
+    outputPath: string;
+} | {
+    kind: "archive-start";
+    currentArchiveName: string;
+    currentArchivePath: string;
+    archiveSizeInBytes: number;
+    archiveIndex: number;
+    totalArchives: number;
+    completedArchives: number;
+    extractedBytes: number;
+    totalBytes: number;
+} | {
+    kind: "archive-complete";
+    currentArchiveName: string;
+    currentArchivePath: string;
+    archiveSizeInBytes: number;
+    archiveIndex: number;
+    totalArchives: number;
+    completedArchives: number;
+    extractedBytes: number;
+    totalBytes: number;
+} | {
+    kind: "archive-failed";
+    currentArchiveName: string;
+    currentArchivePath: string;
+    archiveSizeInBytes: number;
+    archiveIndex: number;
+    totalArchives: number;
+    completedArchives: number;
+    extractedBytes: number;
+    totalBytes: number;
+    errorMessage: string;
+} | {
+    kind: "finish";
+    totalArchives: number;
+    completedArchives: number;
+    failedArchives: number;
+    extractedBytes: number;
+    totalBytes: number;
+    outputPath: string;
+};
+type ExtractionProgressListener = (event: ExtractionProgressEvent) => void;
+declare function extractArchives(inputPath: string, outputPath?: string, onProgress?: ExtractionProgressListener): Promise<ExtractionSummary>;
+
+type InputMode = "unzip" | "already-extracted";
+declare function resolveInputMode(options: {
+    unzip?: boolean;
+    alreadyExtracted?: boolean;
+}): InputMode;
+
+declare const LOG_LEVELS: readonly ["trace", "debug", "info", "warning", "error", "critical", "fatal"];
+type LogLevel = (typeof LOG_LEVELS)[number];
+declare const LOG_STATUSES: readonly ["success", "failure"];
+type LogStatus = (typeof LOG_STATUSES)[number];
+type LogRecord = Record<string, unknown>;
+type StructuredLogEntry = LogRecord & {
+    timestamp: string;
+    level: LogLevel;
+    severity: LogLevel;
+    event: string;
+    kind: string;
+    command?: string;
+    status?: LogStatus;
+    message?: string;
+};
+
+type WriteLogOptions = {
+    baseDirectory?: string;
+    event?: string;
+    level?: LogLevel;
+    status?: LogStatus;
+    message?: string;
+};
+declare function getUserAppDirectoryPath(): string;
+declare function getLogsDirectoryPath(baseDirectory?: string): string;
+declare function writeCommandLog(commandName: string, payload: unknown, baseDirectoryOrOptions?: string | WriteLogOptions, maybeOptions?: Omit<WriteLogOptions, "baseDirectory">): Promise<string>;
+declare function writeCommandFailureLog(commandName: string, error: unknown, input?: {
+    argv?: string[];
+    context?: Record<string, unknown>;
+    baseDirectory?: string;
+    fatal?: boolean;
+}): Promise<string>;
+declare function createJsonLinesLog(commandName: string, baseDirectory?: string): Promise<string>;
+declare function appendJsonLinesLog(filePath: string, payload: unknown, options?: Omit<WriteLogOptions, "baseDirectory" | "status"> & {
+    command?: string;
+    status?: LogStatus;
+}): Promise<void>;
+
+declare function importDataToDatabase(inputPath: string, options?: ImportOptions): Promise<ImportSummary>;
+declare function loadImportDataToStaging(inputPath: string, options?: ImportOptions): Promise<ImportSummary>;
+declare function materializeImportedData(inputPath: string, options?: ImportOptions): Promise<ImportSummary>;
+
+type QuarantineStatsFilters = {
+    dataset?: string;
+    category?: string;
+    stage?: string;
+    retryable?: boolean;
+    terminal?: boolean;
+};
+type QuarantineListFilters = QuarantineStatsFilters & {
+    limit: number;
+    afterId?: number;
+};
+type QuarantineStatsCount = {
+    key: string;
+    count: number;
+};
+type QuarantineStatsSummary = {
+    totalRows: number;
+    retryableRows: number;
+    terminalRows: number;
+    rowsByDataset: QuarantineStatsCount[];
+    rowsByCategory: QuarantineStatsCount[];
+    rowsByStage: QuarantineStatsCount[];
+    appliedFilters: QuarantineStatsFilters;
+};
+type QuarantineListRow = {
+    id: number;
+    dataset: string;
+    filePath: string;
+    rowNumber: number | null;
+    checkpointOffset: number | null;
+    errorCode: string | null;
+    errorCategory: string | null;
+    errorStage: string | null;
+    errorMessage: string;
+    retryCount: number;
+    canRetryLater: boolean;
+    createdAt: string;
+};
+type QuarantineListSummary = {
+    rows: QuarantineListRow[];
+    appliedFilters: QuarantineListFilters;
+};
+type QuarantineRecord = {
+    id: number;
+    dataset: string;
+    filePath: string;
+    rowNumber: number | null;
+    checkpointOffset: number | null;
+    errorCode: string | null;
+    errorCategory: string | null;
+    errorStage: string | null;
+    errorMessage: string;
+    rawLine: string;
+    parsedPayload: Record<string, unknown> | null;
+    sanitizationsApplied: unknown[];
+    retryCount: number;
+    canRetryLater: boolean;
+    createdAt: string;
+};
+
+declare function getQuarantineStats(filters: QuarantineStatsFilters & {
+    dbUrl?: string;
+}): Promise<QuarantineStatsSummary>;
+declare function listQuarantineRows(filters: QuarantineListFilters & {
+    dbUrl?: string;
+}): Promise<QuarantineListSummary>;
+declare function showQuarantineRow(id: number, options?: {
+    dbUrl?: string;
+}): Promise<QuarantineRecord>;
+
+type SanitizeDatasetType = Exclude<DatasetType, "zip-archive" | "unknown">;
+type SanitizeFilePlan = {
+    dataset: SanitizeDatasetType;
+    relativePath: string;
+    absolutePath: string;
+    outputPath: string;
+    displayPath: string;
+    fileSize: number;
+};
+type SanitizePlan = {
+    validatedPath: string;
+    outputPath: string;
+    totalFiles: number;
+    totalBytes: number;
+    datasets: SanitizeDatasetType[];
+    files: SanitizeFilePlan[];
+};
+type SanitizeSummary = {
+    inputPath: string;
+    validatedPath: string;
+    outputPath: string;
+    totalFiles: number;
+    totalBytes: number;
+    processedFiles: number;
+    processedRows: number;
+    nulBytesRemoved: number;
+    changedFiles: number;
+    unchangedFiles: number;
+    datasets: SanitizeDatasetType[];
+    files: Array<{
+        dataset: SanitizeDatasetType;
+        relativePath: string;
+        outputPath: string;
+        lineCount: number;
+        changed: boolean;
+        nulBytesRemoved: number;
+    }>;
+    warnings: string[];
+    nextStep?: string | undefined;
+};
+type SanitizeProgressEvent = {
+    kind: "start";
+    validatedPath: string;
+    outputPath: string;
+    totalFiles: number;
+    totalBytes: number;
+    datasets: SanitizeDatasetType[];
+} | {
+    kind: "progress";
+    currentFileDisplayPath: string;
+    fileIndex: number;
+    totalFiles: number;
+    bytesProcessed: number;
+    totalBytes: number;
+    fileBytesProcessed: number;
+    currentFileSize: number;
+    processedRows: number;
+    nulBytesRemoved: number;
+    changedFiles: number;
+} | {
+    kind: "finish";
+    totalFiles: number;
+    processedRows: number;
+    nulBytesRemoved: number;
+    changedFiles: number;
+    totalBytes: number;
+};
+type SanitizeProgressListener = (event: SanitizeProgressEvent) => void;
+type SanitizeOptions = {
+    outputPath?: string | undefined;
+    dataset?: SanitizeDatasetType | undefined;
+    onProgress?: SanitizeProgressListener | undefined;
+};
+
+declare function sanitizeInputDirectory(inputPath: string, options?: SanitizeOptions): Promise<SanitizeSummary>;
+
+type FederalRevenueReferenceMode = "latest" | "current" | "explicit";
+type FederalRevenueClientOptions = {
+    baseUrl?: string | undefined;
+    shareToken?: string | undefined;
+    userAgent?: string | undefined;
+};
+type FederalRevenueReference = {
+    reference: string;
+    href: string;
+};
+type FederalRevenueFile = {
+    name: string;
+    href: string;
+    downloadUrl: string;
+    sizeInBytes?: number | undefined;
+    lastModified?: string | undefined;
+    etag?: string | undefined;
+};
+type FederalRevenueReferenceSelection = {
+    mode: FederalRevenueReferenceMode;
+    selectedReference: string;
+    availableReferences: string[];
+};
+type FederalRevenueCheckOptions = FederalRevenueClientOptions & {
+    reference?: string | undefined;
+    current?: boolean | undefined;
+};
+type FederalRevenueCheckSummary = {
+    selectedReference: string;
+    selectionMode: FederalRevenueReferenceMode;
+    availableReferences: string[];
+    files: FederalRevenueFile[];
+    totalFiles: number;
+    totalBytes: number;
+    remoteBaseUrl: string;
+};
+type FederalRevenueDownloadStatus = "downloaded" | "skipped" | "failed";
+type FederalRevenueLocalFileStatus = "downloaded" | "failed" | "partial" | "missing";
+type FederalRevenueManifestLastCommand = "download" | "sync" | "retry";
+type FederalRevenueManifestLastStatus = "running" | "completed" | "failed";
+type FederalRevenueManifestFile = {
+    fileName: string;
+    filePath: string;
+    partialFilePath: string;
+    href: string;
+    downloadUrl: string;
+    status: FederalRevenueLocalFileStatus;
+    updatedAt: string;
+    remoteSizeInBytes?: number | undefined;
+    localSizeInBytes?: number | undefined;
+    lastModified?: string | undefined;
+    etag?: string | undefined;
+    downloadedAt?: string | undefined;
+    errorMessage?: string | undefined;
+};
+type FederalRevenueManifest = {
+    version: 1;
+    reference: string;
+    remoteBaseUrl: string;
+    outputPath: string;
+    createdAt: string;
+    updatedAt: string;
+    lastCommand: FederalRevenueManifestLastCommand;
+    lastStatus: FederalRevenueManifestLastStatus;
+    files: FederalRevenueManifestFile[];
+};
+type FederalRevenueDownloadEntry = {
+    fileName: string;
+    filePath: string;
+    status: FederalRevenueDownloadStatus;
+    sizeInBytes?: number | undefined;
+    remoteSizeInBytes?: number | undefined;
+    errorMessage?: string | undefined;
+};
+type FederalRevenueDownloadSummary = {
+    reference: string;
+    selectionMode: FederalRevenueReferenceMode;
+    outputPath: string;
+    manifestPath: string;
+    remoteBaseUrl: string;
+    filesFound: number;
+    downloadedFiles: number;
+    skippedFiles: number;
+    failedFiles: number;
+    partialFiles: number;
+    missingFiles: number;
+    totalBytes: number;
+    downloadedBytes: number;
+    entries: FederalRevenueDownloadEntry[];
+    startedAt: string;
+    finishedAt: string;
+    warnings: string[];
+    nextStep?: string | undefined;
+};
+type FederalRevenueDownloadProgressEvent = {
+    kind: "start";
+    reference: string;
+    outputPath: string;
+    totalFiles: number;
+    totalBytes: number;
+} | {
+    kind: "file-start";
+    reference: string;
+    fileName: string;
+    fileIndex: number;
+    totalFiles: number;
+    completedFiles: number;
+    downloadedBytes: number;
+    totalBytes: number;
+    fileSizeInBytes?: number | undefined;
+} | {
+    kind: "file-complete";
+    reference: string;
+    fileName: string;
+    fileIndex: number;
+    totalFiles: number;
+    completedFiles: number;
+    downloadedBytes: number;
+    totalBytes: number;
+    fileSizeInBytes?: number | undefined;
+} | {
+    kind: "file-skipped";
+    reference: string;
+    fileName: string;
+    fileIndex: number;
+    totalFiles: number;
+    completedFiles: number;
+    downloadedBytes: number;
+    totalBytes: number;
+    fileSizeInBytes?: number | undefined;
+} | {
+    kind: "file-failed";
+    reference: string;
+    fileName: string;
+    fileIndex: number;
+    totalFiles: number;
+    completedFiles: number;
+    downloadedBytes: number;
+    totalBytes: number;
+    errorMessage: string;
+    fileSizeInBytes?: number | undefined;
+} | {
+    kind: "finish";
+    reference: string;
+    outputPath: string;
+    totalFiles: number;
+    downloadedFiles: number;
+    skippedFiles: number;
+    failedFiles: number;
+    downloadedBytes: number;
+    totalBytes: number;
+};
+type FederalRevenueDownloadProgressListener = (event: FederalRevenueDownloadProgressEvent) => void;
+type FederalRevenueDownloadOptions = FederalRevenueCheckOptions & {
+    outputPath?: string | undefined;
+    retries?: number | undefined;
+    overwrite?: boolean | undefined;
+    incompleteOnly?: boolean | undefined;
+    manifestCommand?: FederalRevenueManifestLastCommand | undefined;
+    onProgress?: FederalRevenueDownloadProgressListener | undefined;
+};
+type FederalRevenueSyncLockOptions = {
+    forceLock?: boolean | undefined;
+};
+type FederalRevenueSyncOptions = FederalRevenueDownloadOptions & FederalRevenueSyncLockOptions & {
+    extractOutputPath?: string | undefined;
+    sanitizeOutputPath?: string | undefined;
+    sanitizeOptions?: Omit<SanitizeOptions, "outputPath" | "onProgress"> | undefined;
+    importOptions?: Omit<ImportOptions, "onProgress"> | undefined;
+    onExtractProgress?: ExtractionProgressListener | undefined;
+    onSanitizeProgress?: SanitizeOptions["onProgress"] | undefined;
+    onImportProgress?: ImportOptions["onProgress"] | undefined;
+};
+type FederalRevenueSyncSummary = {
+    reference: string;
+    download: FederalRevenueDownloadSummary;
+    extraction: ExtractionSummary;
+    validation: ValidationSummary;
+    sanitization: SanitizeSummary;
+    import: ImportSummary;
+    startedAt: string;
+    finishedAt: string;
+    warnings: string[];
+};
+type FederalRevenueLocalStatusEntry = {
+    fileName: string;
+    filePath: string;
+    partialFilePath: string;
+    status: FederalRevenueLocalFileStatus;
+    remoteSizeInBytes?: number | undefined;
+    localSizeInBytes?: number | undefined;
+    errorMessage?: string | undefined;
+};
+type FederalRevenueStatusOptions = FederalRevenueCheckOptions & {
+    outputPath?: string | undefined;
+};
+type FederalRevenueStatusSummary = {
+    reference: string;
+    selectionMode: FederalRevenueReferenceMode;
+    outputPath: string;
+    manifestPath: string;
+    manifestFound: boolean;
+    filesFound: number;
+    downloadedFiles: number;
+    failedFiles: number;
+    partialFiles: number;
+    missingFiles: number;
+    totalBytes: number;
+    localBytes: number;
+    isComplete: boolean;
+    entries: FederalRevenueLocalStatusEntry[];
+    warnings: string[];
+    updatedAt?: string | undefined;
+    lastCommand?: FederalRevenueManifestLastCommand | undefined;
+    lastStatus?: FederalRevenueManifestLastStatus | undefined;
+};
+type FederalRevenueRetryOptions = FederalRevenueDownloadOptions;
+type FederalRevenueCleanMode = "partials" | "failed" | "all";
+type FederalRevenueCleanOptions = FederalRevenueCheckOptions & {
+    outputPath?: string | undefined;
+    partials?: boolean | undefined;
+    failed?: boolean | undefined;
+    all?: boolean | undefined;
+};
+type FederalRevenueCleanSummary = {
+    reference: string;
+    selectionMode: FederalRevenueReferenceMode;
+    outputPath: string;
+    manifestPath: string;
+    mode: FederalRevenueCleanMode;
+    removedFiles: number;
+    removedBytes: number;
+    removedPaths: string[];
+    warnings: string[];
+    startedAt: string;
+    finishedAt: string;
+};
+type FederalRevenueLockFile = {
+    reference: string;
+    outputPath: string;
+    lockPath: string;
+    pid: number;
+    token: string;
+    startedAt: string;
+};
+
+declare const DEFAULT_FEDERAL_REVENUE_SHARE_TOKEN = "YggdBLfdninEJX9";
+declare const DEFAULT_FEDERAL_REVENUE_WEBDAV_URL = "https://arquivos.receitafederal.gov.br/public.php/webdav";
+declare const DEFAULT_FEDERAL_REVENUE_USER_AGENT = "cnpj-db-loader federal-revenue-client";
+declare function validateFederalRevenueReference(reference: string): void;
+declare function getCurrentFederalRevenueReference(date?: Date): string;
+declare function listFederalRevenueReferences(options?: FederalRevenueClientOptions): Promise<{
+    references: FederalRevenueReference[];
+    remoteBaseUrl: string;
+}>;
+declare function resolveFederalRevenueReference(input?: {
+    reference?: string | undefined;
+    current?: boolean | undefined;
+} & FederalRevenueClientOptions): Promise<FederalRevenueReferenceSelection>;
+declare function listFederalRevenueFiles(reference: string, options?: FederalRevenueClientOptions): Promise<{
+    files: FederalRevenueFile[];
+    remoteBaseUrl: string;
+}>;
+declare function buildFederalRevenueDownloadHeaders(options?: FederalRevenueClientOptions): Record<string, string>;
+
+declare function checkFederalRevenueDataset(options?: FederalRevenueCheckOptions): Promise<FederalRevenueCheckSummary>;
+declare function downloadFederalRevenueDataset(options?: FederalRevenueDownloadOptions): Promise<FederalRevenueDownloadSummary>;
+declare function retryFederalRevenueDataset(options?: FederalRevenueDownloadOptions): Promise<FederalRevenueDownloadSummary>;
+
+declare function getFederalRevenueStatus(options?: FederalRevenueStatusOptions): Promise<FederalRevenueStatusSummary>;
+
+declare function cleanFederalRevenueDataset(options?: FederalRevenueCleanOptions): Promise<FederalRevenueCleanSummary>;
+
+declare function withFederalRevenueSyncLock<T>(input: {
+    reference: string;
+    outputPath: string;
+    options?: FederalRevenueSyncLockOptions | undefined;
+}, callback: () => Promise<T>): Promise<T>;
+
+declare const FEDERAL_REVENUE_MANIFEST_VERSION = 1;
+declare const FEDERAL_REVENUE_CONTROL_DIR = ".cnpj-db-loader";
+declare const FEDERAL_REVENUE_CONTROL_SCOPE = "federal-revenue";
+declare const DEFAULT_FEDERAL_REVENUE_DOWNLOAD_ROOT: string;
+declare function buildFederalRevenueReferenceOutputPath(reference: string, outputPath?: string): string;
+declare function getFederalRevenueControlDirectory(outputPath: string): string;
+declare function getFederalRevenueManifestPath(outputPath: string): string;
+declare function getFederalRevenueSyncLockPath(outputPath: string): string;
+declare function readFederalRevenueManifest(outputPath: string): Promise<FederalRevenueManifest | undefined>;
+declare function writeFederalRevenueManifest(manifest: FederalRevenueManifest): Promise<void>;
+declare function createFederalRevenueManifest(input: {
+    reference: string;
+    outputPath: string;
+    remoteBaseUrl: string;
+    files: FederalRevenueFile[];
+    lastCommand: FederalRevenueManifestLastCommand;
+}): Promise<FederalRevenueManifest>;
+declare function evaluateFederalRevenueManifestFile(entry: FederalRevenueManifestFile): Promise<FederalRevenueManifestFile>;
+declare function evaluateFederalRevenueManifestFiles(entries: FederalRevenueManifestFile[]): Promise<FederalRevenueManifestFile[]>;
+declare function updateFederalRevenueManifestFile(outputPath: string, input: {
+    fileName: string;
+    status: FederalRevenueLocalFileStatus;
+    localSizeInBytes?: number | undefined;
+    errorMessage?: string | undefined;
+    downloadedAt?: string | undefined;
+}): Promise<void>;
+declare function finalizeFederalRevenueManifest(outputPath: string, lastStatus: FederalRevenueManifest["lastStatus"]): Promise<void>;
+
+declare function syncFederalRevenueDataset(options?: FederalRevenueSyncOptions): Promise<FederalRevenueSyncSummary>;
+
+export { type AppConfig, type AppEnvironment, AppError, type CheckpointCleanupPhase, DEFAULT_FEDERAL_REVENUE_DOWNLOAD_ROOT, DEFAULT_FEDERAL_REVENUE_SHARE_TOKEN, DEFAULT_FEDERAL_REVENUE_USER_AGENT, DEFAULT_FEDERAL_REVENUE_WEBDAV_URL, type DatabaseCleanupSummary, type DatabaseConfig, type DatasetBlock, type DatasetType, type ExtractionEntry, type ExtractionProgressEvent, type ExtractionProgressListener, type ExtractionSummary, FEDERAL_REVENUE_CONTROL_DIR, FEDERAL_REVENUE_CONTROL_SCOPE, FEDERAL_REVENUE_MANIFEST_VERSION, type Failure, type FederalRevenueCheckOptions, type FederalRevenueCheckSummary, type FederalRevenueCleanMode, type FederalRevenueCleanOptions, type FederalRevenueCleanSummary, type FederalRevenueClientOptions, type FederalRevenueDownloadEntry, type FederalRevenueDownloadOptions, type FederalRevenueDownloadProgressEvent, type FederalRevenueDownloadProgressListener, type FederalRevenueDownloadStatus, type FederalRevenueDownloadSummary, type FederalRevenueFile, type FederalRevenueLocalFileStatus, type FederalRevenueLocalStatusEntry, type FederalRevenueLockFile, type FederalRevenueManifest, type FederalRevenueManifestFile, type FederalRevenueManifestLastCommand, type FederalRevenueManifestLastStatus, type FederalRevenueReference, type FederalRevenueReferenceMode, type FederalRevenueReferenceSelection, type FederalRevenueRetryOptions, type FederalRevenueStatusOptions, type FederalRevenueStatusSummary, type FederalRevenueSyncLockOptions, type FederalRevenueSyncOptions, type FederalRevenueSyncSummary, type FileInspection, type ImportCheckpointRecord, type ImportCheckpointStatus, type ImportDatasetPlan, type ImportDatasetType, type ImportFilePlan, type ImportOptions, type ImportPerformanceSummary, type ImportPhaseStatus, type ImportPlanRecord, type ImportProgressEvent, type ImportProgressListener, type ImportSchemaCapabilities, type ImportSummary, type InputDetectionMode, type InputMode, type InspectSummary, type LogLevel, type LogStatus, type QuarantineListFilters, type QuarantineListSummary, type QuarantineRecord, type QuarantineStatsFilters, type QuarantineStatsSummary, type Result, type SanitizeDatasetType, type SanitizeOptions, type SanitizePlan, type SanitizeProgressEvent, type SanitizeProgressListener, type SanitizeSummary, type SchemaGenerationOptions, type SchemaProfile, ServiceError, type StructuredLogEntry, type SupportedOs, ValidationError, type ValidationSummary, appendJsonLinesLog, assertPostgresUrl, buildFederalRevenueDownloadHeaders, buildFederalRevenueReferenceOutputPath, checkFederalRevenueDataset, cleanFederalRevenueDataset, cleanupDatabaseCheckpointsData, cleanupDatabaseMaterializedData, cleanupDatabasePlansData, cleanupDatabaseStagingData, createFederalRevenueManifest, createJsonLinesLog, defaultExtractedOutputPath, detectOs, downloadFederalRevenueDataset, ensureDirectory, evaluateFederalRevenueManifestFile, evaluateFederalRevenueManifestFiles, extractArchives, finalizeFederalRevenueManifest, generateSchemaSql, getAllLayouts, getCurrentFederalRevenueReference, getFederalRevenueControlDirectory, getFederalRevenueManifestPath, getFederalRevenueStatus, getFederalRevenueSyncLockPath, getLayoutSummary, getLogsDirectoryPath, getQuarantineStats, getUserAppDirectoryPath, importDataToDatabase, inspectFiles, listFederalRevenueFiles, listFederalRevenueReferences, listQuarantineRows, loadImportDataToStaging, materializeImportedData, prettyJson, readDatabaseConfig, readFederalRevenueManifest, resetDefaultDbUrl, resolveDatabaseUrl, resolveDbUrl, resolveFederalRevenueReference, resolveInputMode, resolveSchemaProfile, retryFederalRevenueDataset, runDoctor, safeReadText, safeWriteText, sanitizeInputDirectory, setDefaultDbUrl, showQuarantineRow, syncFederalRevenueDataset, testDatabaseConnection, toTitleCase, updateFederalRevenueManifestFile, validateFederalRevenueReference, validateInputDirectory, withFederalRevenueSyncLock, writeCommandFailureLog, writeCommandLog, writeDatabaseConfig, writeFederalRevenueManifest, writeSchemaFile };