@clazic/kordoc 2.4.11 → 2.4.12

package/dist/index.d.cts

@@ -125,6 +125,18 @@ interface ParseOptions {
     ocrBatchSize?: number;
     /** PDF 머리글/바닥글 자동 제거 */
     removeHeaderFooter?: boolean;
+    /**
+     * 부분 파싱 실패 허용 비율 (0~1).
+     * - undefined: 실패 페이지가 있어도 경고만 기록하고 계속 진행
+     * - 예: 0.3이면 대상 페이지의 30%를 초과해 실패 시 오류로 중단
+     */
+    maxPartialFailureRatio?: number;
+    /**
+     * PDF 텍스트 정규화 모드.
+     * - "default": 줄 병합/균등배분 공백 보정 적용 (기본값)
+     * - "strict-preserve": 원문 줄바꿈/공백 보존 우선 (페이지 번호 제거만 수행)
+     */
+    pdfTextNormalization?: "default" | "strict-preserve";
 }
 /** 파싱 중 스킵/실패한 요소 보고 */
 interface ParseWarning {
@@ -320,9 +332,117 @@ declare function detectZipFormat(buffer: ArrayBuffer): Promise<{
 
 declare function blocksToMarkdown(blocks: IRBlock[]): string;
 
+type LogLevel = "error" | "warn" | "info" | "debug" | "trace";
+type LogEventType = "start" | "progress" | "done" | "error" | "message";
+type LogStage = "detect" | "convert" | "render" | "probe" | "ocr" | "proofread" | "merge" | "finalize" | "unknown";
+interface LogEvent {
+    ts?: string;
+    level: LogLevel;
+    runId?: string;
+    stage?: LogStage;
+    event?: LogEventType;
+    component?: string;
+    message: string;
+    meta?: Record<string, unknown>;
+    error?: {
+        code?: string;
+        name?: string;
+        message?: string;
+        stack?: string;
+    };
+}
+interface Logger {
+    log(event: LogEvent): void;
+    child(context: Partial<LogEvent>): Logger;
+    withRun(runId: string): Logger;
+}
+
 /** kordoc 공용 유틸리티 */
+
 declare const VERSION: string;
 
+/**
+ * 다중 API 키 로테이션 + rate-limit 완화 유틸.
+ *
+ * 정책:
+ * - 기본 선택은 라운드 로빈
+ * - 429/5xx/timeout 발생 키는 cooldown 적용
+ * - cooldown 중 키는 제외
+ * - 모든 키가 cooldown이면 가장 빠른 복구 시각을 계산해 안내
+ */
+interface ApiKeyRotationOptions {
+    baseCooldownMs?: number;
+    maxCooldownMs?: number;
+}
+interface KeyHealthSnapshot {
+    keyId: string;
+    totalRequests: number;
+    successCount: number;
+    failureCount: number;
+    consecutiveFailures: number;
+    lastUsedAt?: number;
+    cooldownUntil?: number;
+}
+interface AcquireResult {
+    key: string;
+    keyId: string;
+}
+declare class AllKeysCoolingDownError extends Error {
+    waitMs: number;
+    constructor(waitMs: number);
+}
+declare class ApiKeyRotationPool {
+    private readonly states;
+    private readonly baseCooldownMs;
+    private readonly maxCooldownMs;
+    private cursor;
+    constructor(keys: string[], options?: ApiKeyRotationOptions);
+    static fromEnv(env?: NodeJS.ProcessEnv): ApiKeyRotationPool;
+    acquire(now?: number): AcquireResult;
+    markSuccess(keyId: string): void;
+    markFailure(keyId: string, opts?: {
+        status?: number;
+        retryAfterMs?: number;
+        timeout?: boolean;
+    }, now?: number): void;
+    snapshot(): KeyHealthSnapshot[];
+    private isRetryableFailure;
+    private find;
+}
+
+type UnifiedStage = "convert" | "render" | "probe" | "ocr" | "proofread" | "merge";
+type UnifiedOcrErrorCode = "UNSUPPORTED_INPUT" | "SOFFICE_NOT_FOUND" | "CONVERT_FAILED" | "RENDER_FAILED" | "PROBE_FAILED" | "OCR_FAILED" | "PROOFREAD_FAILED" | "MERGE_FAILED" | "UNKNOWN";
+interface UnifiedOcrProgressEvent {
+    type: "stage_start" | "stage_progress" | "stage_done" | "error";
+    stage: UnifiedStage;
+    stagePercent: number;
+    overallPercent: number;
+    current?: number;
+    total?: number;
+    code?: UnifiedOcrErrorCode;
+    message?: string;
+}
+interface UnifiedOcrOptions {
+    workspaceDir?: string;
+    outputPath?: string;
+    dpi?: number;
+    baseUrl?: string;
+    onEvent?: (event: UnifiedOcrProgressEvent) => void;
+    modelCandidates?: string[];
+    modelMaxTokens?: Record<string, number>;
+    stageWeights?: Partial<Record<UnifiedStage, number>>;
+    timeoutMs?: number;
+    maxRetriesPerPage?: number;
+    logger?: Logger;
+    runId?: string;
+}
+interface UnifiedOcrResult {
+    outputPath: string;
+    reportPath: string;
+    selectedModel: string;
+}
+declare function runUnifiedOcrPipeline(inputPath: string, options?: UnifiedOcrOptions): Promise<UnifiedOcrResult>;
+
 /**
  * kordoc — 모두 파싱해버리겠다
  *
@@ -353,4 +473,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 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 MarkdownToXlsxOptions, type OcrMode, type OcrProvider, type OutlineItem, type ParseFailure, type ParseOptions, type ParseResult, type ParseSuccess, type ParseWarning, type StructuredOcrResult, VERSION, type WarningCode, type WatchOptions, blocksToMarkdown, compare, detectFormat, detectZipFormat, diffBlocks, extractFormFields, isHwpxFile, isOldHwpFile, isPdfFile, isZipFile, markdownToHwpx, markdownToXlsx, parse, parseDocx, parseHwp, parseHwpx, parsePdf, parseXlsx };
+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 };

package/dist/index.d.ts

@@ -125,6 +125,18 @@ interface ParseOptions {
     ocrBatchSize?: number;
     /** PDF 머리글/바닥글 자동 제거 */
     removeHeaderFooter?: boolean;
+    /**
+     * 부분 파싱 실패 허용 비율 (0~1).
+     * - undefined: 실패 페이지가 있어도 경고만 기록하고 계속 진행
+     * - 예: 0.3이면 대상 페이지의 30%를 초과해 실패 시 오류로 중단
+     */
+    maxPartialFailureRatio?: number;
+    /**
+     * PDF 텍스트 정규화 모드.
+     * - "default": 줄 병합/균등배분 공백 보정 적용 (기본값)
+     * - "strict-preserve": 원문 줄바꿈/공백 보존 우선 (페이지 번호 제거만 수행)
+     */
+    pdfTextNormalization?: "default" | "strict-preserve";
 }
 /** 파싱 중 스킵/실패한 요소 보고 */
 interface ParseWarning {
@@ -320,9 +332,117 @@ declare function detectZipFormat(buffer: ArrayBuffer): Promise<{
 
 declare function blocksToMarkdown(blocks: IRBlock[]): string;
 
+type LogLevel = "error" | "warn" | "info" | "debug" | "trace";
+type LogEventType = "start" | "progress" | "done" | "error" | "message";
+type LogStage = "detect" | "convert" | "render" | "probe" | "ocr" | "proofread" | "merge" | "finalize" | "unknown";
+interface LogEvent {
+    ts?: string;
+    level: LogLevel;
+    runId?: string;
+    stage?: LogStage;
+    event?: LogEventType;
+    component?: string;
+    message: string;
+    meta?: Record<string, unknown>;
+    error?: {
+        code?: string;
+        name?: string;
+        message?: string;
+        stack?: string;
+    };
+}
+interface Logger {
+    log(event: LogEvent): void;
+    child(context: Partial<LogEvent>): Logger;
+    withRun(runId: string): Logger;
+}
+
 /** kordoc 공용 유틸리티 */
+
 declare const VERSION: string;
 
+/**
+ * 다중 API 키 로테이션 + rate-limit 완화 유틸.
+ *
+ * 정책:
+ * - 기본 선택은 라운드 로빈
+ * - 429/5xx/timeout 발생 키는 cooldown 적용
+ * - cooldown 중 키는 제외
+ * - 모든 키가 cooldown이면 가장 빠른 복구 시각을 계산해 안내
+ */
+interface ApiKeyRotationOptions {
+    baseCooldownMs?: number;
+    maxCooldownMs?: number;
+}
+interface KeyHealthSnapshot {
+    keyId: string;
+    totalRequests: number;
+    successCount: number;
+    failureCount: number;
+    consecutiveFailures: number;
+    lastUsedAt?: number;
+    cooldownUntil?: number;
+}
+interface AcquireResult {
+    key: string;
+    keyId: string;
+}
+declare class AllKeysCoolingDownError extends Error {
+    waitMs: number;
+    constructor(waitMs: number);
+}
+declare class ApiKeyRotationPool {
+    private readonly states;
+    private readonly baseCooldownMs;
+    private readonly maxCooldownMs;
+    private cursor;
+    constructor(keys: string[], options?: ApiKeyRotationOptions);
+    static fromEnv(env?: NodeJS.ProcessEnv): ApiKeyRotationPool;
+    acquire(now?: number): AcquireResult;
+    markSuccess(keyId: string): void;
+    markFailure(keyId: string, opts?: {
+        status?: number;
+        retryAfterMs?: number;
+        timeout?: boolean;
+    }, now?: number): void;
+    snapshot(): KeyHealthSnapshot[];
+    private isRetryableFailure;
+    private find;
+}
+
+type UnifiedStage = "convert" | "render" | "probe" | "ocr" | "proofread" | "merge";
+type UnifiedOcrErrorCode = "UNSUPPORTED_INPUT" | "SOFFICE_NOT_FOUND" | "CONVERT_FAILED" | "RENDER_FAILED" | "PROBE_FAILED" | "OCR_FAILED" | "PROOFREAD_FAILED" | "MERGE_FAILED" | "UNKNOWN";
+interface UnifiedOcrProgressEvent {
+    type: "stage_start" | "stage_progress" | "stage_done" | "error";
+    stage: UnifiedStage;
+    stagePercent: number;
+    overallPercent: number;
+    current?: number;
+    total?: number;
+    code?: UnifiedOcrErrorCode;
+    message?: string;
+}
+interface UnifiedOcrOptions {
+    workspaceDir?: string;
+    outputPath?: string;
+    dpi?: number;
+    baseUrl?: string;
+    onEvent?: (event: UnifiedOcrProgressEvent) => void;
+    modelCandidates?: string[];
+    modelMaxTokens?: Record<string, number>;
+    stageWeights?: Partial<Record<UnifiedStage, number>>;
+    timeoutMs?: number;
+    maxRetriesPerPage?: number;
+    logger?: Logger;
+    runId?: string;
+}
+interface UnifiedOcrResult {
+    outputPath: string;
+    reportPath: string;
+    selectedModel: string;
+}
+declare function runUnifiedOcrPipeline(inputPath: string, options?: UnifiedOcrOptions): Promise<UnifiedOcrResult>;
+
 /**
  * kordoc — 모두 파싱해버리겠다
  *
@@ -353,4 +473,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 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 MarkdownToXlsxOptions, type OcrMode, type OcrProvider, type OutlineItem, type ParseFailure, type ParseOptions, type ParseResult, type ParseSuccess, type ParseWarning, type StructuredOcrResult, VERSION, type WarningCode, type WatchOptions, blocksToMarkdown, compare, detectFormat, detectZipFormat, diffBlocks, extractFormFields, isHwpxFile, isOldHwpFile, isPdfFile, isZipFile, markdownToHwpx, markdownToXlsx, parse, parseDocx, parseHwp, parseHwpx, parsePdf, parseXlsx };
+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 };