@clazic/kordoc 2.6.0 → 2.7.0

package/dist/index.d.cts

@@ -251,6 +251,61 @@ interface WatchOptions {
     pages?: string;
     silent?: boolean;
 }
+/** 포맷 감지 단계 이벤트 */
+interface ConvertDetectEvent {
+    type: "detect";
+    stage: "reading" | "format_detected" | "size_check";
+    message: string;
+    fileSize?: number;
+    format?: "hwp" | "hwpx";
+}
+/** 환경 검증 단계 이벤트 */
+interface ConvertValidateEvent {
+    type: "validate";
+    stage: "soffice_check" | "soffice_found" | "soffice_not_found";
+    message: string;
+    sofficePath?: string;
+}
+/** 설치 단계 이벤트 */
+interface ConvertInstallEvent {
+    type: "install";
+    stage: "install_start" | "download_progress" | "extract_progress" | "install_complete" | "install_failed";
+    message: string;
+    percent?: number;
+    downloadedBytes?: number;
+    totalBytes?: number;
+    installedPath?: string;
+    error?: string;
+}
+/** 변환 진행 이벤트 */
+interface ConvertProgressEvent {
+    type: "convert";
+    stage: "convert_start" | "convert_progress" | "convert_done";
+    message: string;
+    percent: number;
+}
+/** 변환 완료 이벤트 */
+interface ConvertCompleteEvent {
+    type: "complete";
+    stage: "success";
+    message: string;
+    result: {
+        sourceFormat: "hwp" | "hwpx";
+        pdfSize: number;
+        pageCount?: number;
+    };
+}
+/** 에러 이벤트 */
+interface ConvertErrorEvent {
+    type: "error";
+    stage: "detect" | "validate" | "install" | "convert";
+    message: string;
+    code: ErrorCode;
+    recoverable: boolean;
+    suggestion?: string;
+}
+/** convertToPdf()에서 발생하는 모든 이벤트 */
+type ConvertEvent = ConvertDetectEvent | ConvertValidateEvent | ConvertInstallEvent | ConvertProgressEvent | ConvertCompleteEvent | ConvertErrorEvent;
 /** HWP/HWPX → PDF 변환 옵션 */
 interface ConvertToPdfOptions {
     /** 페이지 범위 ("1-3,5,7-10") — LibreOffice 필터가 지원하는 경우 */
@@ -259,8 +314,15 @@ interface ConvertToPdfOptions {
     quality?: "low" | "medium" | "high";
     /** 타임아웃 (ms, 기본 60000) */
     timeoutMs?: number;
-    /** 진행 상황 콜백 */
+    /**
+     * 진행 상황 콜백 (deprecated — onEvent 사용 권장)
+     * @deprecated onEvent를 사용하세요
+     */
     onProgress?: (percent: number, stage: string) => void;
+    /**
+     * 이벤트 콜백 — 모든 진행 상황을 이벤트로 전달
+     */
+    onEvent?: (event: ConvertEvent) => void;
     /** LibreOffice 자동 설치 허용 (기본 true) */
     autoInstallLibreOffice?: boolean;
     /** LibreOffice 바이너리 직접 지정 */
@@ -362,16 +424,10 @@ declare function markdownToXlsx(markdown: string, options?: MarkdownToXlsxOption
 declare function convertToPdf(input: string | ArrayBuffer | Buffer, options?: ConvertToPdfOptions): Promise<ConvertToPdfResult>;
 /**
  * HWP 5.x 파일을 PDF로 변환 (포맷 감지 생략).
- * 내부적으로 convertToPdf와 동일하지만 강제로 "hwp"로 처리.
- *
- * @deprecated convertToPdf()에 Buffer를 직접 전달하는 것과 동일
  */
 declare function convertHwpToPdf(input: string | ArrayBuffer | Buffer, options?: ConvertToPdfOptions): Promise<ConvertToPdfResult>;
 /**
  * HWPX 파일을 PDF로 변환 (포맷 감지 생략).
- * 내부적으로 convertToPdf와 동일하지만 강제로 "hwpx"로 처리.
- *
- * @deprecated convertToPdf()에 Buffer를 직접 전달하는 것과 동일
  */
 declare function convertHwpxToPdf(input: string | ArrayBuffer | Buffer, options?: ConvertToPdfOptions): Promise<ConvertToPdfResult>;
 
@@ -493,12 +549,14 @@ interface UnifiedOcrProgressEvent {
     pageNumber?: number;
     workerCount?: number;
 }
+/** unified-ocr에서 onEvent로 전달되는 보조 이벤트 — LibreOffice 설치/검증/에러 */
+type UnifiedOcrAuxEvent = ConvertInstallEvent | ConvertValidateEvent | ConvertErrorEvent;
 interface UnifiedOcrOptions {
     workspaceDir?: string;
     outputPath?: string;
     dpi?: number;
     baseUrl?: string;
-    onEvent?: (event: UnifiedOcrProgressEvent) => void;
+    onEvent?: (event: UnifiedOcrProgressEvent | UnifiedOcrAuxEvent) => void;
     modelCandidates?: string[];
     modelMaxTokens?: Record<string, number>;
     stageWeights?: Partial<Record<UnifiedStage, number>>;
@@ -508,6 +566,10 @@ interface UnifiedOcrOptions {
     logger?: Logger;
     runId?: string;
     concurrencyPerKey?: number;
+    /** LibreOffice 자동 설치 허용 (기본 false) — convert 단계에서 install/validate 이벤트가 onEvent로 전달됨 */
+    autoInstallLibreOffice?: boolean;
+    /** LibreOffice 바이너리 직접 지정 (선택) — 지정 시 자동 탐색/설치 건너뜀 */
+    sofficePath?: string;
 }
 interface UnifiedOcrResult {
     outputPath: string;
@@ -546,4 +608,4 @@ declare function parseXlsx(buffer: ArrayBuffer, options?: ParseOptions, zip?: JS
 /** DOCX 파일을 Markdown으로 변환 */
 declare function parseDocx(buffer: ArrayBuffer, options?: ParseOptions, zip?: JSZip): Promise<ParseResult>;
 
-export { type AcquireResult, AllKeysCoolingDownError, type ApiKeyRotationOptions, ApiKeyRotationPool, type BlockDiff, type BoundingBox, type CellContext, type CellDiff, type ConvertToPdfFailure, type ConvertToPdfOptions, type ConvertToPdfResult, type ConvertToPdfSuccess, type DiffChangeType, type DiffResult, type DocumentMetadata, type ErrorCode, type ExtractedImage, type FileType, type FormField, type FormResult, type IRBlock, type IRBlockType, type IRCell, type IRTable, type ImageData, type InlineStyle, type KeyHealthSnapshot, type MarkdownToXlsxOptions, type OcrMode, type OcrProvider, type OutlineItem, type ParseFailure, type ParseOptions, type ParseResult, type ParseSuccess, type ParseWarning, type StructuredOcrResult, type UnifiedOcrOptions, type UnifiedOcrProgressEvent, type UnifiedOcrResult, type UnifiedStage, VERSION, type WarningCode, type WatchOptions, blocksToMarkdown, compare, convertHwpToPdf, convertHwpxToPdf, convertToPdf, detectFormat, detectZipFormat, diffBlocks, extractFormFields, isHwpxFile, isOldHwpFile, isPdfFile, isZipFile, markdownToHwpx, markdownToXlsx, parse, parseDocx, parseHwp, parseHwpx, parsePdf, parseXlsx, runUnifiedOcrPipeline };
+export { type AcquireResult, AllKeysCoolingDownError, type ApiKeyRotationOptions, ApiKeyRotationPool, type BlockDiff, type BoundingBox, type CellContext, type CellDiff, type ConvertErrorEvent, type ConvertInstallEvent, type ConvertToPdfFailure, type ConvertToPdfOptions, type ConvertToPdfResult, type ConvertToPdfSuccess, type ConvertValidateEvent, type DiffChangeType, type DiffResult, type DocumentMetadata, type ErrorCode, type ExtractedImage, type FileType, type FormField, type FormResult, type IRBlock, type IRBlockType, type IRCell, type IRTable, type ImageData, type InlineStyle, type KeyHealthSnapshot, type MarkdownToXlsxOptions, type OcrMode, type OcrProvider, type OutlineItem, type ParseFailure, type ParseOptions, type ParseResult, type ParseSuccess, type ParseWarning, type StructuredOcrResult, type UnifiedOcrAuxEvent, type UnifiedOcrOptions, type UnifiedOcrProgressEvent, type UnifiedOcrResult, type UnifiedStage, VERSION, type WarningCode, type WatchOptions, blocksToMarkdown, compare, convertHwpToPdf, convertHwpxToPdf, convertToPdf, detectFormat, detectZipFormat, diffBlocks, extractFormFields, isHwpxFile, isOldHwpFile, isPdfFile, isZipFile, markdownToHwpx, markdownToXlsx, parse, parseDocx, parseHwp, parseHwpx, parsePdf, parseXlsx, runUnifiedOcrPipeline };

package/dist/index.d.ts

@@ -251,6 +251,61 @@ interface WatchOptions {
     pages?: string;
     silent?: boolean;
 }
+/** 포맷 감지 단계 이벤트 */
+interface ConvertDetectEvent {
+    type: "detect";
+    stage: "reading" | "format_detected" | "size_check";
+    message: string;
+    fileSize?: number;
+    format?: "hwp" | "hwpx";
+}
+/** 환경 검증 단계 이벤트 */
+interface ConvertValidateEvent {
+    type: "validate";
+    stage: "soffice_check" | "soffice_found" | "soffice_not_found";
+    message: string;
+    sofficePath?: string;
+}
+/** 설치 단계 이벤트 */
+interface ConvertInstallEvent {
+    type: "install";
+    stage: "install_start" | "download_progress" | "extract_progress" | "install_complete" | "install_failed";
+    message: string;
+    percent?: number;
+    downloadedBytes?: number;
+    totalBytes?: number;
+    installedPath?: string;
+    error?: string;
+}
+/** 변환 진행 이벤트 */
+interface ConvertProgressEvent {
+    type: "convert";
+    stage: "convert_start" | "convert_progress" | "convert_done";
+    message: string;
+    percent: number;
+}
+/** 변환 완료 이벤트 */
+interface ConvertCompleteEvent {
+    type: "complete";
+    stage: "success";
+    message: string;
+    result: {
+        sourceFormat: "hwp" | "hwpx";
+        pdfSize: number;
+        pageCount?: number;
+    };
+}
+/** 에러 이벤트 */
+interface ConvertErrorEvent {
+    type: "error";
+    stage: "detect" | "validate" | "install" | "convert";
+    message: string;
+    code: ErrorCode;
+    recoverable: boolean;
+    suggestion?: string;
+}
+/** convertToPdf()에서 발생하는 모든 이벤트 */
+type ConvertEvent = ConvertDetectEvent | ConvertValidateEvent | ConvertInstallEvent | ConvertProgressEvent | ConvertCompleteEvent | ConvertErrorEvent;
 /** HWP/HWPX → PDF 변환 옵션 */
 interface ConvertToPdfOptions {
     /** 페이지 범위 ("1-3,5,7-10") — LibreOffice 필터가 지원하는 경우 */
@@ -259,8 +314,15 @@ interface ConvertToPdfOptions {
     quality?: "low" | "medium" | "high";
     /** 타임아웃 (ms, 기본 60000) */
     timeoutMs?: number;
-    /** 진행 상황 콜백 */
+    /**
+     * 진행 상황 콜백 (deprecated — onEvent 사용 권장)
+     * @deprecated onEvent를 사용하세요
+     */
     onProgress?: (percent: number, stage: string) => void;
+    /**
+     * 이벤트 콜백 — 모든 진행 상황을 이벤트로 전달
+     */
+    onEvent?: (event: ConvertEvent) => void;
     /** LibreOffice 자동 설치 허용 (기본 true) */
     autoInstallLibreOffice?: boolean;
     /** LibreOffice 바이너리 직접 지정 */
@@ -362,16 +424,10 @@ declare function markdownToXlsx(markdown: string, options?: MarkdownToXlsxOption
 declare function convertToPdf(input: string | ArrayBuffer | Buffer, options?: ConvertToPdfOptions): Promise<ConvertToPdfResult>;
 /**
  * HWP 5.x 파일을 PDF로 변환 (포맷 감지 생략).
- * 내부적으로 convertToPdf와 동일하지만 강제로 "hwp"로 처리.
- *
- * @deprecated convertToPdf()에 Buffer를 직접 전달하는 것과 동일
  */
 declare function convertHwpToPdf(input: string | ArrayBuffer | Buffer, options?: ConvertToPdfOptions): Promise<ConvertToPdfResult>;
 /**
  * HWPX 파일을 PDF로 변환 (포맷 감지 생략).
- * 내부적으로 convertToPdf와 동일하지만 강제로 "hwpx"로 처리.
- *
- * @deprecated convertToPdf()에 Buffer를 직접 전달하는 것과 동일
  */
 declare function convertHwpxToPdf(input: string | ArrayBuffer | Buffer, options?: ConvertToPdfOptions): Promise<ConvertToPdfResult>;
 
@@ -493,12 +549,14 @@ interface UnifiedOcrProgressEvent {
     pageNumber?: number;
     workerCount?: number;
 }
+/** unified-ocr에서 onEvent로 전달되는 보조 이벤트 — LibreOffice 설치/검증/에러 */
+type UnifiedOcrAuxEvent = ConvertInstallEvent | ConvertValidateEvent | ConvertErrorEvent;
 interface UnifiedOcrOptions {
     workspaceDir?: string;
     outputPath?: string;
     dpi?: number;
     baseUrl?: string;
-    onEvent?: (event: UnifiedOcrProgressEvent) => void;
+    onEvent?: (event: UnifiedOcrProgressEvent | UnifiedOcrAuxEvent) => void;
     modelCandidates?: string[];
     modelMaxTokens?: Record<string, number>;
     stageWeights?: Partial<Record<UnifiedStage, number>>;
@@ -508,6 +566,10 @@ interface UnifiedOcrOptions {
     logger?: Logger;
     runId?: string;
     concurrencyPerKey?: number;
+    /** LibreOffice 자동 설치 허용 (기본 false) — convert 단계에서 install/validate 이벤트가 onEvent로 전달됨 */
+    autoInstallLibreOffice?: boolean;
+    /** LibreOffice 바이너리 직접 지정 (선택) — 지정 시 자동 탐색/설치 건너뜀 */
+    sofficePath?: string;
 }
 interface UnifiedOcrResult {
     outputPath: string;
@@ -546,4 +608,4 @@ declare function parseXlsx(buffer: ArrayBuffer, options?: ParseOptions, zip?: JS
 /** DOCX 파일을 Markdown으로 변환 */
 declare function parseDocx(buffer: ArrayBuffer, options?: ParseOptions, zip?: JSZip): Promise<ParseResult>;
 
-export { type AcquireResult, AllKeysCoolingDownError, type ApiKeyRotationOptions, ApiKeyRotationPool, type BlockDiff, type BoundingBox, type CellContext, type CellDiff, type ConvertToPdfFailure, type ConvertToPdfOptions, type ConvertToPdfResult, type ConvertToPdfSuccess, type DiffChangeType, type DiffResult, type DocumentMetadata, type ErrorCode, type ExtractedImage, type FileType, type FormField, type FormResult, type IRBlock, type IRBlockType, type IRCell, type IRTable, type ImageData, type InlineStyle, type KeyHealthSnapshot, type MarkdownToXlsxOptions, type OcrMode, type OcrProvider, type OutlineItem, type ParseFailure, type ParseOptions, type ParseResult, type ParseSuccess, type ParseWarning, type StructuredOcrResult, type UnifiedOcrOptions, type UnifiedOcrProgressEvent, type UnifiedOcrResult, type UnifiedStage, VERSION, type WarningCode, type WatchOptions, blocksToMarkdown, compare, convertHwpToPdf, convertHwpxToPdf, convertToPdf, detectFormat, detectZipFormat, diffBlocks, extractFormFields, isHwpxFile, isOldHwpFile, isPdfFile, isZipFile, markdownToHwpx, markdownToXlsx, parse, parseDocx, parseHwp, parseHwpx, parsePdf, parseXlsx, runUnifiedOcrPipeline };
+export { type AcquireResult, AllKeysCoolingDownError, type ApiKeyRotationOptions, ApiKeyRotationPool, type BlockDiff, type BoundingBox, type CellContext, type CellDiff, type ConvertErrorEvent, type ConvertInstallEvent, type ConvertToPdfFailure, type ConvertToPdfOptions, type ConvertToPdfResult, type ConvertToPdfSuccess, type ConvertValidateEvent, type DiffChangeType, type DiffResult, type DocumentMetadata, type ErrorCode, type ExtractedImage, type FileType, type FormField, type FormResult, type IRBlock, type IRBlockType, type IRCell, type IRTable, type ImageData, type InlineStyle, type KeyHealthSnapshot, type MarkdownToXlsxOptions, type OcrMode, type OcrProvider, type OutlineItem, type ParseFailure, type ParseOptions, type ParseResult, type ParseSuccess, type ParseWarning, type StructuredOcrResult, type UnifiedOcrAuxEvent, type UnifiedOcrOptions, type UnifiedOcrProgressEvent, type UnifiedOcrResult, type UnifiedStage, VERSION, type WarningCode, type WatchOptions, blocksToMarkdown, compare, convertHwpToPdf, convertHwpxToPdf, convertToPdf, detectFormat, detectZipFormat, diffBlocks, extractFormFields, isHwpxFile, isOldHwpFile, isPdfFile, isZipFile, markdownToHwpx, markdownToXlsx, parse, parseDocx, parseHwp, parseHwpx, parsePdf, parseXlsx, runUnifiedOcrPipeline };