@clazic/kordoc 2.5.2 → 2.6.1

package/dist/index.d.cts

@@ -154,7 +154,7 @@ interface OutlineItem {
     pageNumber?: number;
 }
 /** 구조화된 에러 코드 — 프로그래밍적 에러 핸들링용 */
-type ErrorCode = "EMPTY_INPUT" | "UNSUPPORTED_FORMAT" | "ENCRYPTED" | "DRM_PROTECTED" | "CORRUPTED" | "DECOMPRESSION_BOMB" | "ZIP_BOMB" | "IMAGE_BASED_PDF" | "NO_SECTIONS" | "PARSE_ERROR" | "FILE_TOO_LARGE";
+type ErrorCode = "EMPTY_INPUT" | "UNSUPPORTED_FORMAT" | "ENCRYPTED" | "DRM_PROTECTED" | "CORRUPTED" | "DECOMPRESSION_BOMB" | "ZIP_BOMB" | "IMAGE_BASED_PDF" | "NO_SECTIONS" | "PARSE_ERROR" | "FILE_TOO_LARGE" | "CONVERT_FAILED" | "TIMEOUT" | "SOFFICE_NOT_FOUND" | "UNSUPPORTED_PLATFORM";
 type FileType = "hwpx" | "hwp" | "pdf" | "xlsx" | "docx" | "image" | "unknown";
 interface ParseResultBase {
     fileType: FileType;
@@ -251,6 +251,105 @@ 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 필터가 지원하는 경우 */
+    pages?: string;
+    /** 품질/압축 설정 (미래 확장) */
+    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 바이너리 직접 지정 */
+    sofficePath?: string;
+}
+/** PDF 변환 성공 결과 */
+interface ConvertToPdfSuccess {
+    success: true;
+    /** PDF 바이너리 */
+    pdf: Uint8Array;
+    /** 원본 파일 형식 */
+    sourceFormat: "hwp" | "hwpx";
+    /** 페이지 수 (확인 가능한 경우) */
+    pageCount?: number;
+}
+/** PDF 변환 실패 결과 */
+interface ConvertToPdfFailure {
+    success: false;
+    /** 에러 코드 */
+    code: ErrorCode;
+    /** 상세 에러 메시지 */
+    error: string;
+    /** 실패한 단계 */
+    stage?: "detect" | "validate" | "convert";
+}
+/** PDF 변환 결과 (discriminated union) */
+type ConvertToPdfResult = ConvertToPdfSuccess | ConvertToPdfFailure;
 
 /** 문서 비교 엔진 — IR 레벨 블록 비교로 신구대조표 생성 */
 
@@ -306,6 +405,32 @@ interface MarkdownToXlsxOptions {
  */
 declare function markdownToXlsx(markdown: string, options?: MarkdownToXlsxOptions): Promise<ArrayBuffer>;
 
+/**
+ * HWP/HWPX 파일을 PDF로 변환.
+ *
+ * @param input 파일 경로, Buffer, 또는 ArrayBuffer
+ * @param options 변환 옵션
+ * @returns 변환 결과 (성공/실패 discriminated union)
+ *
+ * @example
+ * ```ts
+ * import { convertToPdf } from "kordoc"
+ * const result = await convertToPdf("document.hwp")
+ * if (result.success) {
+ *   await writeFile("output.pdf", result.pdf)
+ * }
+ * ```
+ */
+declare function convertToPdf(input: string | ArrayBuffer | Buffer, options?: ConvertToPdfOptions): Promise<ConvertToPdfResult>;
+/**
+ * HWP 5.x 파일을 PDF로 변환 (포맷 감지 생략).
+ */
+declare function convertHwpToPdf(input: string | ArrayBuffer | Buffer, options?: ConvertToPdfOptions): Promise<ConvertToPdfResult>;
+/**
+ * HWPX 파일을 PDF로 변환 (포맷 감지 생략).
+ */
+declare function convertHwpxToPdf(input: string | ArrayBuffer | Buffer, options?: ConvertToPdfOptions): Promise<ConvertToPdfResult>;
+
 /** 매직 바이트 기반 파일 포맷 감지 */
 
 /** ZIP 파일 여부: PK\x03\x04 */
@@ -477,4 +602,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 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, 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 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 };

package/dist/index.d.ts

@@ -154,7 +154,7 @@ interface OutlineItem {
     pageNumber?: number;
 }
 /** 구조화된 에러 코드 — 프로그래밍적 에러 핸들링용 */
-type ErrorCode = "EMPTY_INPUT" | "UNSUPPORTED_FORMAT" | "ENCRYPTED" | "DRM_PROTECTED" | "CORRUPTED" | "DECOMPRESSION_BOMB" | "ZIP_BOMB" | "IMAGE_BASED_PDF" | "NO_SECTIONS" | "PARSE_ERROR" | "FILE_TOO_LARGE";
+type ErrorCode = "EMPTY_INPUT" | "UNSUPPORTED_FORMAT" | "ENCRYPTED" | "DRM_PROTECTED" | "CORRUPTED" | "DECOMPRESSION_BOMB" | "ZIP_BOMB" | "IMAGE_BASED_PDF" | "NO_SECTIONS" | "PARSE_ERROR" | "FILE_TOO_LARGE" | "CONVERT_FAILED" | "TIMEOUT" | "SOFFICE_NOT_FOUND" | "UNSUPPORTED_PLATFORM";
 type FileType = "hwpx" | "hwp" | "pdf" | "xlsx" | "docx" | "image" | "unknown";
 interface ParseResultBase {
     fileType: FileType;
@@ -251,6 +251,105 @@ 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 필터가 지원하는 경우 */
+    pages?: string;
+    /** 품질/압축 설정 (미래 확장) */
+    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 바이너리 직접 지정 */
+    sofficePath?: string;
+}
+/** PDF 변환 성공 결과 */
+interface ConvertToPdfSuccess {
+    success: true;
+    /** PDF 바이너리 */
+    pdf: Uint8Array;
+    /** 원본 파일 형식 */
+    sourceFormat: "hwp" | "hwpx";
+    /** 페이지 수 (확인 가능한 경우) */
+    pageCount?: number;
+}
+/** PDF 변환 실패 결과 */
+interface ConvertToPdfFailure {
+    success: false;
+    /** 에러 코드 */
+    code: ErrorCode;
+    /** 상세 에러 메시지 */
+    error: string;
+    /** 실패한 단계 */
+    stage?: "detect" | "validate" | "convert";
+}
+/** PDF 변환 결과 (discriminated union) */
+type ConvertToPdfResult = ConvertToPdfSuccess | ConvertToPdfFailure;
 
 /** 문서 비교 엔진 — IR 레벨 블록 비교로 신구대조표 생성 */
 
@@ -306,6 +405,32 @@ interface MarkdownToXlsxOptions {
  */
 declare function markdownToXlsx(markdown: string, options?: MarkdownToXlsxOptions): Promise<ArrayBuffer>;
 
+/**
+ * HWP/HWPX 파일을 PDF로 변환.
+ *
+ * @param input 파일 경로, Buffer, 또는 ArrayBuffer
+ * @param options 변환 옵션
+ * @returns 변환 결과 (성공/실패 discriminated union)
+ *
+ * @example
+ * ```ts
+ * import { convertToPdf } from "kordoc"
+ * const result = await convertToPdf("document.hwp")
+ * if (result.success) {
+ *   await writeFile("output.pdf", result.pdf)
+ * }
+ * ```
+ */
+declare function convertToPdf(input: string | ArrayBuffer | Buffer, options?: ConvertToPdfOptions): Promise<ConvertToPdfResult>;
+/**
+ * HWP 5.x 파일을 PDF로 변환 (포맷 감지 생략).
+ */
+declare function convertHwpToPdf(input: string | ArrayBuffer | Buffer, options?: ConvertToPdfOptions): Promise<ConvertToPdfResult>;
+/**
+ * HWPX 파일을 PDF로 변환 (포맷 감지 생략).
+ */
+declare function convertHwpxToPdf(input: string | ArrayBuffer | Buffer, options?: ConvertToPdfOptions): Promise<ConvertToPdfResult>;
+
 /** 매직 바이트 기반 파일 포맷 감지 */
 
 /** ZIP 파일 여부: PK\x03\x04 */
@@ -477,4 +602,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 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, 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 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 };