@rscc/common-core 0.1.2 → 0.3.0

package/dist/index.d.ts

@@ -247,6 +247,22 @@ interface ApiClientConfig {
      * - onUnauthorized 는 시도마다 발화될 수 있다 (기본 판정에선 401 비재시도라 1회).
      */
     retry?: ApiClientRetryOptions;
+    /**
+     * 지정 시 대상 메서드 요청에 멱등성 키 헤더를 자동 부착한다 (contracts/idempotency.md).
+     * 미지정 = 미부착(현행 동작).
+     *
+     * - 키는 {@link generateIdempotencyKey} 로 **논리 호출당 1회** 생성된다 —
+     *   sentTraceId 와 같은 위치(재시도 클로저 밖)라 재시도 전 시도에 동일 키가
+     *   부착된다 ("같은 논리 작업 = 같은 키" 계약의 자동화).
+     * - 호출자가 이미 같은 이름의 헤더를 실었으면 덮어쓰지 않는다 (호출자 우선).
+     * - 새 논리 호출(새 request)은 새 키를 생성한다.
+     */
+    idempotency?: {
+        /** 멱등성 키 헤더명. 기본 "Idempotency-Key". */
+        header?: string;
+        /** 부착 대상 메서드(대문자). 기본 ["POST","PATCH"] — 비멱등 메서드만. */
+        methods?: string[];
+    };
     /**
      * true 면 성공(2xx) 응답의 본문이 유효한 JSON 이 아닐 때(본문 읽기 `text()` 실패 포함)
      * 조용히 null 을 반환하지 않고 code "INVALID_JSON" 의 ApiError 를 throw 한다
@@ -299,6 +315,11 @@ interface ApiClient {
  *
  * 동작 (contracts/common-response.schema.json, trace.md):
  * - 매 요청에 traceId 를 생성해 traceIdHeader(기본 X-Trace-Id)로 부착한다.
+ * - `Content-Type: application/json` 은 호출자가 Content-Type 을 지정하지 않았고 body 가
+ *   **문자열**일 때만 기본 부착한다 (JSON.stringify 관용). body 없는 요청(GET 등)엔 붙이지
+ *   않아 교차 출처 GET 의 CORS preflight 를 유발하지 않으며, URLSearchParams/Blob/FormData/
+ *   ArrayBuffer/ReadableStream 등은 fetch 기본값에 맡긴다. 문자열이지만 JSON 이 아닌 본문은
+ *   Content-Type 을 직접 지정할 것.
  * - 응답이 CommonResponse 봉투면 success 검사 후 data 를 언랩한다
  *   (data 부재 시 undefined). 비봉투 JSON 은 그대로 반환.
  * - 실패 봉투 / HTTP 에러는 code·message·traceId 를 담은 ApiError 를 throw.
@@ -559,9 +580,13 @@ declare function createTtlCache<K, V>(options: TtlCacheOptions): TtlCache<K, V>;
  * 경량 서킷 브레이커. 런타임 의존성 0 (native 만).
  *
  * Java `com.rscc.common.util.CircuitBreaker` / Python `rscc_common.circuit_breaker` 와
- * 시맨틱 동일 (3언어 공유 벡터 CB-01~09 — 각 언어 테스트에 수동 동기화. Python 은
+ * 시맨틱 동일 (3언어 공유 벡터 CB-01~13 — 각 언어 테스트에 수동 동기화. Python 은
  * 시간 단위가 초 — `초 × 1000 == ms`).
  *
+ * - **권장 사용법 — `execute(fn)`**: 게이트(allowRequest) → 실행 → 결과 보고를 한 번에
+ *   처리해 보고를 **정확히 1회** 보장한다. 차단 시 {@link CircuitOpenError} 로 reject
+ *   (fn 미호출), 취소(`name === "AbortError"`)는 성공·실패 어느 쪽에도 집계하지 않는다
+ *   (onIgnore — CB-12). 수동 게이트(allowRequest + 보고)는 execute 로 감쌀 수 없는 경우에만.
  * - **연속(consecutive) 실패 카운트**: `onFailure()` 가 failureThreshold 에 도달(`>=`)하면
  *   OPEN. `onSuccess()` 는 카운터를 0 으로 리셋한다 (슬라이딩 윈도 비채택 — 단순성).
  * - **lazy 전이**: OPEN → HALF_OPEN 전이는 `allowRequest()` 호출 시점에 판정한다
@@ -570,38 +595,51 @@ declare function createTtlCache<K, V>(options: TtlCacheOptions): TtlCache<K, V>;
  * - **HALF_OPEN 프로브 1개**: 프로브가 진행 중이면 나머지 `allowRequest()` 는 false.
  *   프로브 성공 → CLOSED(카운터 0), 프로브 실패 → OPEN 재진입(openedAt 갱신 —
  *   전체 openDurationMs 재대기).
- * - **결과 보고 규율**: `allowRequest()==true` 를 받은 호출만 `onSuccess()`/`onFailure()`
- *   를 **정확히 1회** 호출한다 (try/finally 로 보고 보장 권장 — 보고 누락은 아래 프로브
- *   보류를 무기한 지속시킨다). OPEN 대기 중 늦게 도착한 보고는 상태·openedAt·카운터를
- *   바꾸지 않고(no-op — CB-08) 미보고 그랜트 잔량만 소진한다.
+ * - **결과 보고 규율**: `allowRequest()==true` 를 받은 호출만 `onSuccess()`/`onFailure()`/
+ *   `onIgnore()` 중 하나를 **정확히 1회** 호출한다 (수동 게이트라면 try/catch 로 보고 보장 —
+ *   성공·실패로 판정할 수 없는 취소 등은 `onIgnore()` 로 그랜트만 반납). OPEN 대기 중 늦게
+ *   도착한 보고는 상태·openedAt·카운터를 바꾸지 않고(no-op — CB-08) 미보고 그랜트 잔량만
+ *   소진한다.
  * - **스테일 그랜트 격리**: CLOSED 시절 그랜트가 아직 보고되지 않은 동안에는
  *   openDurationMs 가 경과해도 HALF_OPEN 전이(프로브)가 보류된다 — 스테일 보고가 프로브
- *   결과로 오인되는 것을 막아 HALF_OPEN 중 도착하는 보고는 항상 프로브의 것이다 (CB-09).
+ *   결과로 오인되는 것을 막아 HALF_OPEN 중 도착하는 보고는 (아래 용서 이후의 매우 늦은
+ *   보고를 제외하면) 항상 프로브의 것이다 (CB-09).
+ * - **유실 그랜트 용서 (2× 규칙)**: 보고가 끝내 오지 않는 그랜트(보고 누락·유실)가 위 보류를
+ *   무기한 지속시켜 서킷이 OPEN 에 영구 고착되는 것을 막는다 — OPEN 진입 후
+ *   `2 × openDurationMs` 경과 시점에도 미보고 그랜트가 남아 있으면 이를 유실로 간주해 0 으로
+ *   용서하고 정상 HALF_OPEN 전이 + 프로브 획득을 수행한다 (CB-10). 용서 뒤 매우 늦은 스테일
+ *   보고가 HALF_OPEN 중 도착하면 프로브 결과로 취급되지만 무해하다 — 스테일 성공은 하류가
+ *   실제로 응답했다는 증거이고, 스테일 실패는 보수적인 OPEN 재진입일 뿐이다 (스테일
+ *   onIgnore 는 프로브 슬롯을 조기 해제해 프로브가 1개 더 허가될 뿐 — 최초 보고가 판정).
+ * - **유실 프로브 용서**: HALF_OPEN 프로브가 openDurationMs(`>=`) 동안 보고되지 않으면 유실로
+ *   간주해 다음 allowRequest() 에 새 프로브를 넘긴다 — 보고 누락 프로브 1개로 HALF_OPEN 에 영구
+ *   고착되는 것을 막는다 (CB-13). 옛 프로브의 늦은 보고는 새 프로브 결과로 취급되며 위와 같은
+ *   이유로 무해하다.
+ *
+ * @example 권장 — execute 로 게이트·보고를 위임한다.
+ * ```ts
+ * const cb = createCircuitBreaker({ failureThreshold: 5, openDurationMs: 30_000 });
+ * const user = await cb.execute(() => api.request<User>("/users/1")); // OPEN 이면 CircuitOpenError
+ * ```
  *
- * @example 서킷 + 재시도 조합 — 시도 직전 allowRequest 게이트, 결과를 브레이커에 보고.
- * OPEN 차단 오류는 shouldRetry 에서 비재시도로 걸러 즉시 실패시킨다(빠른 실패 유지).
+ * @example 서킷 + 재시도 조합 — 시도마다 execute 로 게이트·보고. OPEN 차단
+ * ({@link CircuitOpenError})은 shouldRetry 에서 비재시도로 걸러 즉시 실패시킨다(빠른 실패 유지).
  * ```ts
  * const cb = createCircuitBreaker({ failureThreshold: 5, openDurationMs: 30_000 });
- * const circuitOpen = new Error("서킷 OPEN — 요청 차단");
- * await retry(
- *   async () => {
- *     if (!cb.allowRequest()) throw circuitOpen;
- *     try {
- *       const r = await call();
- *       cb.onSuccess();
- *       return r;
- *     } catch (error) {
- *       cb.onFailure();
- *       throw error;
- *     }
- *   },
- *   {
- *     shouldRetry: (error) => error !== circuitOpen, // OPEN 차단은 즉시 실패
- *     onRetry: (error, attempt, delayMs) => console.warn(`재시도 ${attempt} (${delayMs}ms)`),
- *   }
- * );
+ * await retry(() => cb.execute(() => call()), {
+ *   shouldRetry: (error) => !(error instanceof CircuitOpenError), // OPEN 차단은 즉시 실패
+ *   onRetry: (error, attempt, delayMs) => console.warn(`재시도 ${attempt} (${delayMs}ms)`),
+ * });
  * ```
  */
+/**
+ * 서킷 차단 거부 오류 — `execute()` 가 allowRequest()==false(OPEN 대기·프로브 보류·HALF_OPEN
+ * 프로브 경합)일 때 reject 하며, 이때 작업 함수는 **호출되지 않는다** (CB-12).
+ * Java `CircuitOpenException` / Python `CircuitOpenError` 패리티. 재시도 조합에서 비재시도 신호로 쓴다.
+ */
+declare class CircuitOpenError extends Error {
+    constructor(message?: string);
+}
 type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
 interface CircuitBreakerOptions {
     /** OPEN 전이 임계 — 연속 실패가 이 값에 도달(`>=`)하면 OPEN. 필수 양의 정수 (아니면 RangeError). */
@@ -615,14 +653,32 @@ interface CircuitBreaker {
     /**
      * 요청 통과 여부 — CLOSED 는 true, OPEN 대기 중 false, openDurationMs 경과 시
      * HALF_OPEN 전이 + 프로브 슬롯 획득(true) — 단 CLOSED 시절 미보고 그랜트가 남아 있으면
-     * 전이를 보류하고 false (CB-09). HALF_OPEN 프로브 경합 시 나머지 false.
-     * true 를 받은 호출만 결과를 onSuccess()/onFailure() 로 보고해야 한다.
+     * 전이를 보류하고 false (CB-09), 보류는 OPEN 진입 후 `2 × openDurationMs` 까지만 —
+     * 그 시점엔 미보고 그랜트를 유실로 용서하고 전이 + 프로브 획득(true) (CB-10).
+     * HALF_OPEN 프로브 경합 시 나머지 false — 단 프로브가 openDurationMs 경과(`>=`)까지
+     * 미보고면 유실로 간주해 이 호출에 새 프로브를 넘긴다(true) (CB-13).
+     * true 를 받은 호출만 결과를 onSuccess()/onFailure()/onIgnore() 중 하나로 보고해야 한다.
      */
     allowRequest(): boolean;
     /** 성공 보고 — CLOSED 카운터 리셋, HALF_OPEN 프로브 성공 시 CLOSED 복귀. OPEN 중엔 무시. */
     onSuccess(): void;
     /** 실패 보고 — CLOSED 연속 카운트 증가(임계 도달 시 OPEN), HALF_OPEN 프로브 실패 시 OPEN 재진입. OPEN 중엔 무시. */
     onFailure(): void;
+    /**
+     * 결과 없는 그랜트 반납 — 취소(abort) 등 성공·실패로 판정할 수 없는 호출이 보고 대신
+     * 호출한다 (CB-11). CLOSED: 미보고 그랜트만 반납(연속 실패 카운터 무변화). HALF_OPEN:
+     * 프로브 슬롯 해제 — HALF_OPEN 유지, 다음 allowRequest() 가 새 프로브를 획득한다.
+     * OPEN: 미보고 그랜트 잔량만 소진(그 외 무변화).
+     */
+    onIgnore(): void;
+    /**
+     * fn 래핑 (권장 사용법) — allowRequest() 게이트 → 실행 → 결과 보고를 **정확히 1회** 보장한다.
+     * 거부는 reject(CircuitOpenError) — 동기 throw 아님, 거부 시 fn 은 호출되지 않는다.
+     * resolve → onSuccess() 후 값 반환. throw/reject 는 `name === "AbortError"` 면 onIgnore(),
+     * 그 외(TimeoutError 포함)는 onFailure() 후 **같은 값을 래핑 없이** 다시 throw 한다 (CB-12).
+     * fn 의 동기 throw 도 동일하게 처리된다.
+     */
+    execute<T>(fn: () => T | PromiseLike<T>): Promise<T>;
     /** 현재 상태 조회 — lazy 전이 특성상 openDurationMs 경과 후에도 allowRequest() 전엔 OPEN 으로 보고된다. */
     state(): CircuitState;
 }
@@ -756,4 +812,539 @@ declare function isValidBusinessNumber(value: string | null | undefined): boolea
  */
 declare function isValidCorporateNumber(value: string | null | undefined): boolean;
 
-export { type ApiClient, type ApiClientConfig, type ApiClientRetryOptions, ApiError, type ApiErrorInfo, type ApiRequestInfo, type ApiResponseInfo, type ApiResult, type Bulkhead, BulkheadFullError, type BulkheadOptions, type CircuitBreaker, type CircuitBreakerOptions, type CircuitState, type CommonResponse, type FieldErrorDetail, type PageResponse, ResultCode, type RetryOptions, type SseCallbacks, type SseFrameEvent, type SseSource, type TokenBucket, type TokenBucketOptions, type TtlCache, type TtlCacheOptions, type ValidationErrorData, createApiClient, createBulkhead, createCircuitBreaker, createTokenBucket, createTtlCache, decodeJwtPayload, getTokenExpiry, isChosungQuery, isRetryableStatus, isTokenExpired, isValidBusinessNumber, isValidCorporateNumber, isValidationErrorData, maskCardNumber, maskEmail, maskName, maskPhone, maskSecret, normalizeBusinessNumber, parseRetryAfterMs, parseSseFrame, parseWireDateTime, readSseStream, retry, sanitizeLogValue, stripZone, toChosung, toWireDate, toWireDateTime };
+/**
+ * 멱등성 키 생성 — contracts/idempotency.md (수동 동기화).
+ *
+ * 비멱등 메서드(POST/PATCH)의 실수 재전송이 부수효과를 중복 실행하지 않도록,
+ * 클라이언트가 논리 요청당 고유 키를 `Idempotency-Key` 헤더로 보낸다.
+ * 키 형식: `^[A-Za-z0-9_-]{1,128}$` — UUIDv4(36자, 하이픈 포함) 권장.
+ *
+ * "같은 논리 작업 = 같은 키, 새 작업 = 새 키" 가 핵심이다 — 재시도 루프
+ * **바깥에서 1회 생성**해 전 시도에 동일 부착해야 한다. apiClient 의
+ * `idempotency` 옵션은 이를 자동화한다 (키가 재시도 클로저 밖에서 생성됨).
+ */
+/**
+ * 멱등성 키 신규 생성 — `crypto.randomUUID()` 우선(UUIDv4), 부재 환경에서는
+ * Math.random 기반 8-4-4-4-12 hex 폴백 (generateTraceId 관용구 — 형식 동일).
+ * 두 경로 모두 계약 형식 `[A-Za-z0-9_-]{1,128}` 을 만족한다.
+ */
+declare function generateIdempotencyKey(): string;
+
+/**
+ * 웹훅 서명 — HMAC-SHA256. contracts/webhook-signature.md (수동 동기화).
+ *
+ * Java `com.rscc.common.crypto.WebhookSignature` / Python `rscc_common.webhook`
+ * 과 동일 규칙 (3언어 공유 골든 벡터 WS-01~07).
+ *
+ * - 서명 대상: `"{t}.{rawBody}"` — 본문은 **원문 바이트 그대로**(재직렬화 금지).
+ * - 서명: HMAC-SHA256 의 lowercase hex 64자. secret 은 UTF-8 바이트.
+ * - 헤더 값: `t=<unix초>,v1=<hex>[,v1=<hex>...]` — 다중 v1 = 무중단 시크릿
+ *   로테이션(어느 하나라도 일치하면 유효). 미지 key(v0/v2 등)는 무시.
+ *
+ * [주의] 언어별 시그니처 비대칭 — 계약 문서 인용: "JS 구현은 async 다 —
+ * WebCrypto(`crypto.subtle.sign`)가 Promise 기반이라 signWebhook/verifyWebhook 은
+ * Promise<string>/Promise<boolean> 을 반환한다. Java/Python 은 동기다.
+ * 시맨틱(입력→판정)은 3언어 동일하며 반환 형태만 다르다."
+ *
+ * Node 전용 API(`timingSafeEqual` 등) 미사용 — 브라우저/Node 공용
+ * (`globalThis.crypto.subtle`, Node 18+ / 모던 브라우저).
+ */
+/** 웹훅 서명 헤더명 기본값 (contracts/webhook-signature.md). */
+declare const WEBHOOK_SIGNATURE_HEADER = "X-Rscc-Signature";
+/**
+ * 웹훅 서명 헤더 값을 생성한다 (발신측) — 반환값이 `X-Rscc-Signature` 헤더
+ * 값 전체(`t=<unix초>,v1=<hex>`)다.
+ *
+ * 시크릿 로테이션 기간에는 신·구 시크릿으로 각각 sign 한 뒤 `v1` 을 병기해
+ * 발송한다 (`t=...,v1=<신>,v1=<구>` — t 가 같으므로 두 번째 결과의 `v1=` 부분만
+ * 이어 붙이면 된다).
+ *
+ * @param secret 서명 시크릿 (UTF-8 인코딩 후 HMAC 키로 사용).
+ * @param payload 요청 본문 — **원문 그대로** (파싱·재직렬화 금지, 계약).
+ * @param timestampSeconds 발신 시각 unix 초.
+ */
+declare function signWebhook(secret: string, payload: string | Uint8Array, timestampSeconds: number): Promise<string>;
+/**
+ * 웹훅 서명을 검증한다 (수신측) — 형식 오류·스큐 초과·전 후보 불일치 모두
+ * 예외 없이 **false** 를 반환한다 (호출부 분기 단순화, 계약).
+ *
+ * 판정 절차: 헤더 파싱(t 정확히 1개·정수, v1 1개 이상) → 시계 스큐
+ * `|now - t| ≤ toleranceSeconds`(경계 포함) → 보유 시크릿 각각 × 헤더의 각 v1
+ * 상수시간 대조, 하나라도 일치 → true.
+ *
+ * @param opts.header 수신한 `X-Rscc-Signature` 헤더 값 (부재 시 null → false).
+ * @param opts.payload 수신한 요청 본문 — raw 바이트/원문 문자열.
+ * @param opts.secrets 보유 시크릿 (단일 또는 배열 — 로테이션 기간 신·구 병행).
+ * @param opts.toleranceSeconds 허용 스큐(초). 기본 300.
+ * @param opts.nowSeconds 현재 시각 unix 초 주입 (테스트용). 기본 시스템 시계.
+ */
+declare function verifyWebhook(opts: {
+    header: string | null;
+    payload: string | Uint8Array;
+    secrets: string | string[];
+    toleranceSeconds?: number;
+    nowSeconds?: number;
+}): Promise<boolean>;
+
+/**
+ * 벌크/부분 실패 봉투 — BulkResult. contracts/bulk.md (수동 동기화).
+ *
+ * Java `com.rscc.common.response.BulkResult` / Python `rscc_common.bulk` 와
+ * 동일 와이어 계약 (3언어 공유 골든 벡터 BK-01~04).
+ *
+ * - 항상 `CommonResponse` 봉투의 `data` 자리에 실린다.
+ * - **항목 성공/실패 판정은 `code` 유무다** — code 있으면 실패, 없으면 성공.
+ * - 실패 항목은 items 에 전량 필수 기재, 성공 항목은 id 전달 필요 시만 기재.
+ * - 부분 실패여도 HTTP 200 + `success: true` (벌크 연산 자체는 수행됨).
+ * - `total == succeeded + failed` 불변식.
+ */
+/**
+ * 항목별 처리 상세 — `index` 는 **요청 배열에서의 0-기점 인덱스**(필수,
+ * 원본 항목과 대응시키는 유일 키). `code` 존재 = 실패 항목.
+ */
+interface BulkResultItem {
+    /** 요청 배열에서의 0-기점 인덱스 (필수). */
+    index: number;
+    /** 실패 사유 코드 — error-codes.yaml 코드 문자열 재사용. **존재 = 실패 항목**. */
+    code?: string;
+    /** 실패 사유 한국어 메시지 (실패 항목이면 기재). */
+    message?: string;
+    /** 성공 항목이 생성/영향을 준 리소스 식별자 (전달 필요 시만). */
+    id?: string;
+}
+/** 벌크 처리 결과 페이로드 — `total == succeeded + failed` 불변식. */
+interface BulkResult {
+    /** 요청에 담긴 전체 항목 수. */
+    total: number;
+    /** 성공 항목 수. */
+    succeeded: number;
+    /** 실패 항목 수. */
+    failed: number;
+    /** 항목별 상세 — 실패 전량 필수, 성공은 선택. 전량 성공·id 없음이면 `[]`. */
+    items: BulkResultItem[];
+}
+/**
+ * 값이 BulkResult 와이어 형태인지 판별하는 타입 가드 — total/succeeded/failed 가
+ * number, items 가 배열이고 각 요소에 number `index` 가 있는지만 검사한다.
+ * 선택 키(code/message/id)·미지 키는 검사하지 않는다 (관용적 읽기 —
+ * isValidationErrorData 관용구, 새 선택 키 추가는 non-breaking).
+ */
+declare function isBulkResult(value: unknown): value is BulkResult;
+/** 실패 항목만 추출한다 — 판정 기준은 `code` 유무 (계약 규칙 1). */
+declare function bulkFailures(result: BulkResult): BulkResultItem[];
+/** BulkResult 빌더 — success/failure 를 순서대로 기록하고 build 로 확정한다. */
+interface BulkResultBuilder {
+    /** 성공 항목 기록 — `id` 를 준 경우에만 items 에 기재된다 (응답 크기 억제). */
+    success(index: number, id?: string): BulkResultBuilder;
+    /** 실패 항목 기록 — items 에 반드시 기재된다 (code·message 필수, 계약 규칙 1·2). */
+    failure(index: number, code: string, message: string): BulkResultBuilder;
+    /** total/succeeded/failed 자동 계산으로 BulkResult 를 확정한다. */
+    build(): BulkResult;
+}
+/**
+ * BulkResult 빌더 생성 — 서버/BFF 측에서 항목별 처리 결과를 순서대로 기록한다.
+ *
+ * ```ts
+ * const result = createBulkResultBuilder()
+ *   .success(0, "ord_001")
+ *   .failure(1, "400", "수량은 1 이상이어야 합니다.")
+ *   .success(2) // id 없음 — items 미기재
+ *   .build(); // { total: 3, succeeded: 2, failed: 1, items: [...] }
+ * ```
+ */
+declare function createBulkResultBuilder(): BulkResultBuilder;
+
+/**
+ * 파일 업로드 검증 — 크기·확장자·매직바이트. contracts/file-upload.md (수동 동기화).
+ *
+ * Java `com.rscc.common.util.FileSniffer` / Python `rscc_common.upload` 와
+ * 동일 계약 (3언어 공유 골든 벡터 MB-01~11).
+ *
+ * **브라우저 프리검증이다** — 업로드 전에 사용자에게 즉시 피드백을 주는 용도이며,
+ * 프리검증 통과가 서버 검증을 대체하지 않는다 (보안 경계는 항상 서버).
+ *
+ * - 판정은 **컨테이너 수준**: docx/hwpx 는 `zip`, hwp(5.0)/doc 는 `cfbf` 로
+ *   판정된다 (내부 구조 열람은 비범위).
+ * - 판정 우선순위는 계약 테이블 위→아래, 첫 일치 kind 반환.
+ */
+/** 매직바이트 판정 결과 kind — 3언어 공유 소문자 문자열 (계약 테이블 고정). */
+type FileKind = "png" | "jpeg" | "gif" | "webp" | "pdf" | "zip" | "cfbf" | "hwp3";
+/**
+ * 선두 바이트의 매직바이트를 대조해 파일 kind 를 판정한다 — 계약 테이블
+ * 위→아래 첫 일치, 전부 불일치·빈 입력·시그니처보다 짧은 head 는 null.
+ *
+ * @param head 파일 선두 바이트 (webp 판정에 최대 12바이트 필요 — File.slice
+ *   등으로 앞부분만 읽어 넘기면 된다).
+ */
+declare function sniffFile(head: ArrayBuffer | Uint8Array): FileKind | null;
+/**
+ * 확장자가 허용하는 kind 집합 — 계약 매핑표 고정. 미지 확장자는 빈 집합.
+ * 대소문자 무시, 선행 `.` 은 허용(제거 후 비교).
+ */
+declare function kindsForExtension(ext: string): ReadonlySet<FileKind>;
+/** validateUpload 결과 — ok:false 면 첫 위반 사유·계약 메시지를 담는다. */
+type UploadValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "size" | "extension" | "content-mismatch";
+    message: string;
+};
+/**
+ * 업로드 파일 3중 검증 (브라우저 프리검증) — 순서: (1) 크기 ≤ maxSizeBytes →
+ * (2) 확장자 ∈ allowedExtensions → (3) 매직바이트 kind ∈ 확장자 허용 kind.
+ * 첫 위반의 사유·메시지(계약 문구)를 결과 객체로 반환한다 (예외 없음).
+ *
+ * 계약 매핑표에 없는 확장자를 allowlist 에 넣으려면 `extraMappings` 로 확장자 →
+ * 허용 kind 배열을 주입해야 한다(주입 확장자는 기본 표를 대체 — Python
+ * `extra_mappings` / Java `extraMappings` 대응). 매핑이 없는 허용 확장자는 콘텐츠
+ * 대조가 불가능해 콘텐츠 불일치로 거부된다 (Python 과 동일 판정 — 조용한 통과 금지).
+ *
+ * @param input.fileName 파일명 (확장자는 마지막 `.` 뒤, 대소문자 무시).
+ * @param input.size 파일 크기 바이트 (File.size).
+ * @param input.head 파일 선두 바이트 (12바이트 이상 권장 — webp 최대 요구량).
+ * @param input.maxSizeBytes 크기 상한 (엔드포인트 정책).
+ * @param input.allowedExtensions 허용 확장자 allowlist (대소문자 무시).
+ * @param input.extraMappings 확장자 → 허용 kind 확장 주입 (선택). 키는 소문자·
+ *   선행 `.` 없는 확장자.
+ */
+declare function validateUpload(input: {
+    fileName: string;
+    size: number;
+    head: ArrayBuffer | Uint8Array;
+    maxSizeBytes: number;
+    allowedExtensions: readonly string[];
+    extraMappings?: Readonly<Record<string, readonly FileKind[]>>;
+}): UploadValidationResult;
+
+/**
+ * 목록 조회 쿼리 빌더 — page/size/sort. contracts/query-params.md (수동 동기화).
+ *
+ * 요청 **생성측** 빌더다 — 서버 파서(Java `SortWhitelist`/`PageParams`,
+ * Python `rscc_common.query`)와 왕복 일치하는 쿼리스트링을 만든다.
+ *
+ * - sort 문법: `sort=<field>[,<direction>]` — 같은 이름 반복으로 다중 정렬
+ *   (선언 순서 = 정렬 우선순위). direction 생략 시 서버 기본 asc.
+ * - 예약 이름 `page`/`size`/`sort` 를 필터 이름으로 재사용하면 throw (계약).
+ */
+/** 정렬 지정 1건 — direction 생략 시 값에 방향을 싣지 않는다 (서버 기본 asc). */
+interface SortParam {
+    /** 정렬 필드 — 서버 화이트리스트와 정확 일치해야 한다 (대소문자 구분). */
+    field: string;
+    /** 정렬 방향. 생략 시 asc (서버 기본). */
+    direction?: "asc" | "desc";
+}
+/** buildListQuery 입력 — 전 필드 선택 (지정한 것만 쿼리에 실린다). */
+interface ListQueryOptions {
+    /** 페이지 번호 — 0-기점 (contracts/pagination.md 와 동일 기점). */
+    page?: number;
+    /** 페이지 크기. */
+    size?: number;
+    /** 다중 정렬 — 배열 순서 = 정렬 우선순위 (순서 보존). */
+    sort?: readonly SortParam[];
+    /**
+     * 필터 파라미터 (엔드포인트 고유 스키마). 배열 값은 같은 이름으로 반복 기재,
+     * null/undefined 값은 생략. 예약 이름 page/size/sort 는 금지 — RangeError.
+     */
+    filters?: Record<string, string | number | boolean | readonly (string | number | boolean)[] | null | undefined>;
+}
+/**
+ * 목록 조회 쿼리스트링을 조립한다 — `URLSearchParams` 반환
+ * (`toString()` 하면 서버 파서와 왕복 일치: `page=2&size=50&sort=name%2Cdesc`).
+ *
+ * @throws RangeError filters 키가 예약 이름(page/size/sort)인 경우.
+ */
+declare function buildListQuery(options: ListQueryOptions): URLSearchParams;
+
+/**
+ * 피처 플래그 읽기 — boolean 파싱 통일. contracts/feature-flags.md (수동 동기화).
+ *
+ * Java `com.rscc.common.util.FeatureFlags` / Python `rscc_common.feature_flags`
+ * 와 동일 파싱 규칙 (3언어 공유 골든 벡터 FF-01~06).
+ *
+ * - 참 집합은 **정확히 `{"true","1","on","yes"}`** — 대소문자 무시·trim.
+ *   그 외 전부 false ("y"·"t"·"enabled" 불인정 — 오타는 기능 꺼짐, 안전한 쪽).
+ * - **키 부재(→default)와 값 불인식(→false)은 다르다** — 잘못 쓴 설정 값이
+ *   default 뒤로 숨지 않게 한다.
+ * - JS 는 주입된 소스 객체만 본다 — **env 폴백 없음** (브라우저엔 env 가 없다,
+ *   계약 명시). 빌드타임 치환·서버 전달 설정 객체를 소스로 주입한다.
+ */
+/**
+ * 플래그 값을 boolean 으로 파싱한다 — 문자열은 trim·소문자화 후 참 집합
+ * `{"true","1","on","yes"}` 대조, boolean 은 그대로, null/undefined 는 false.
+ */
+declare function parseFlag(value: string | boolean | null | undefined): boolean;
+/** 피처 플래그 리더 — 주입된 소스 객체에서 boolean 플래그를 읽는다. */
+interface FeatureFlagReader {
+    /**
+     * 플래그 조회 — 키 부재 시 defaultValue(기본 false), 키 존재 시
+     * {@link parseFlag} 판정 결과 (불인식 값 → false, default 미적용).
+     */
+    isEnabled(key: string, defaultValue?: boolean): boolean;
+}
+/**
+ * 피처 플래그 리더 생성 — 소스 객체(빌드타임 치환·서버 전달 설정)를 주입한다.
+ * 키는 논리 키 그대로 조회한다 (예: `"search.rerank"`).
+ *
+ * ```ts
+ * const flags = createFeatureFlags({ "search.rerank": "on" });
+ * flags.isEnabled("search.rerank"); // true
+ * flags.isEnabled("upload.hwp-preview", true); // 키 부재 → default true
+ * ```
+ */
+declare function createFeatureFlags(source: Record<string, string | boolean | undefined>): FeatureFlagReader;
+
+/**
+ * 주민등록번호·외국인등록번호(13자리) 형식 검증.
+ *
+ * **[중요] 2020-10 이후 발급분은 뒷자리(성별코드 제외 6자리)가 임의번호라서
+ * mod-11 체크섬이 성립하지 않는다** — 따라서 기본 검증({@link isValidRrn})은
+ * 체크섬을 포함하지 않고, 레거시 체크섬은 {@link rrnChecksumOkLegacy} 로 분리한다.
+ *
+ * 원천: Java `RrnUtils` / Python `rrn.py` 와 동일 규칙 (수동 동기화).
+ *
+ * 검증 범위: 13자리 형식 + 성별코드(1~8) + 생년월일 실존(윤년 포함 실제 달력).
+ * **미래 날짜 검증은 비범위** — 기준 시점이 없는 순수 함수이므로 하지 않는다.
+ * 정규화는 하이픈·스페이스·탭만 제거(bizno 파리티), 숫자 판정은 ASCII `[0-9]` 만
+ * (전각 숫자 무효).
+ *
+ * ⚠️ 수집 최소화: 주민등록번호는 법령상 처리 근거가 있을 때만 취급하고, 저장 시
+ * 암호화 의무(개인정보보호법 제24조의2)가 있으며, 검증 목적 달성 즉시 파기를
+ * 권장한다.
+ */
+/**
+ * 주민등록번호 표기에서 하이픈(`-`)·스페이스(` `)·탭(`\t`)을 위치 불문 제거한다.
+ * 그 외 문자는 보존한다(검증 단계에서 무효 처리).
+ */
+declare function normalizeRrn(value: string): string;
+/**
+ * 기본 검증 = 13자리 형식 + 성별코드 1~8 + 생년월일 실존(윤년 포함 실제 달력).
+ * **체크섬 미포함** — 2020-10 이후 발급분은 뒷자리가 임의번호라 mod-11 이 성립하지
+ * 않는다. null/undefined·형식 위반은 false (예외 없음).
+ */
+declare function isValidRrn(value: string | null | undefined): boolean;
+/**
+ * 외국인등록번호 여부 — {@link isValidRrn} 을 통과하고 성별코드가 5~8 이면 true.
+ * 무효한 값은 false.
+ */
+declare function isForeignerRrn(value: string | null | undefined): boolean;
+/**
+ * 레거시 mod-11 체크섬 검증 — **2020-10 이전 발급분 한정**. 이후 발급분은
+ * 임의번호라서 유효한 번호도 false 가 나올 수 있으므로, 유효성 판정에 쓰지 말 것.
+ *
+ * 검증식: 가중치 `[2,3,4,5,6,7,8,9,2,3,4,5]`, `check = (11 − sum%11) % 10`,
+ * **외국인(성별코드 5~8)은 `(check+2) % 10` 보정** 후 13번째 자리와 대조.
+ * 기본 검증({@link isValidRrn}) 불통과 값은 false.
+ */
+declare function rrnChecksumOkLegacy(value: string | null | undefined): boolean;
+/**
+ * 생년월일을 `"YYYY-MM-DD"` 문자열로 추출한다(타임존 함정 차단 — `Date` 미사용).
+ * 세기는 성별코드로 판정. 무효한 번호는 null.
+ */
+declare function rrnBirthDate(value: string | null | undefined): string | null;
+
+/**
+ * 한국어 조사 자동 선택 — 받침 유무에 따라 은/는·이/가 등을 고른다.
+ *
+ * 원천: Java `JosaUtils` / Python `text/josa.py` 와 동일 규칙 (수동 동기화).
+ *
+ * 판정 규칙:
+ * - 끝 공백(스페이스·탭)을 스킵한 마지막 문자로 판정
+ * - 한글 음절 → `jong = (c − 0xAC00) % 28` (0 = 받침 없음)
+ * - 숫자(ASCII 0~9) → 독음 음절(`영일이삼사오육칠팔구`)로 치환 후 동일 판정
+ * - 그 외(영문·기호·빈 문자열) → 병기형 `은(는)/이(가)/을(를)/과(와)/(으)로/아(야)`
+ * - (으)로 특례: 받침 없음 또는 ㄹ 받침(jong==8) → "로", 그 외 받침 → "으로"
+ */
+/** 지원하는 조사 쌍 — 이 6종 외 값은 런타임에서도 RangeError. */
+type JosaPair = "은/는" | "이/가" | "을/를" | "과/와" | "(으)로" | "아/야";
+/**
+ * 단어에 어울리는 조사를 고른다 (조사만 반환).
+ * 판정 불가(영문·기호·빈 문자열)면 병기형(`은(는)` 등)을 반환한다.
+ * 지원하지 않는 조사 쌍은 RangeError.
+ */
+declare function pickJosa(word: string, josa: JosaPair): string;
+/**
+ * 단어 뒤에 어울리는 조사를 붙여 반환한다 (`attachJosa("사과", "은/는")` → `"사과는"`).
+ * 판정에서 스킵한 끝 공백(스페이스·탭)은 출력에서도 제거한다
+ * (`"필드 "` → `"필드는"` — 벡터 JO-12).
+ */
+declare function attachJosa(word: string, josa: JosaPair): string;
+
+/**
+ * 한국식 나이 계산 3종 — 만 나이·연 나이·보험 나이.
+ *
+ * 원천: Java `KoreanAgeUtils` / Python `age.py` 와 동일 규칙 (수동 동기화).
+ *
+ * 입력은 **`"YYYY-MM-DD"` 문자열 고정** (`Date` 객체 금지 — JS Date 의 타임존
+ * 함정 원천 차단). 형식 위반·실존하지 않는 날짜·`기준일 < 생일` 은 RangeError.
+ */
+/**
+ * 만 나이 — 생일이 지나지 않았으면 1 을 뺀다 (민법 기준).
+ * 2/29 생은 평년 3/1 에 증가한다(월·일 튜플 비교 — Java `Period` 시맨틱과 일치).
+ */
+declare function ageMan(birth: string, on: string): number;
+/** 연 나이 — 연도 차이만 계산한다 (청소년 보호법 등의 연 나이). */
+declare function ageByYear(birth: string, on: string): number;
+/**
+ * 보험 나이 — 만 개월수 `m`(당월 일 미도달 시 −1) 기준 `⌊(m+6)/12⌋`.
+ * 생후 6개월이 지난 시점(상령일)마다 한 살씩 올라간다.
+ */
+declare function ageInsurance(birth: string, on: string): number;
+
+/**
+ * 한국 전화번호 정규화·분류·포맷·E.164 변환.
+ *
+ * 원천: Java `PhoneNumberUtils` / Python `phone.py` 와 동일 규칙 (수동 동기화).
+ *
+ * 타입 문자열(`mobile|landline|voip|safe|m2m|unknown`)은 3언어 공유 소문자
+ * 와이어 값이다.
+ *
+ * 로그·화면 노출 권장 경로: `formatPhoneNumber(normalizePhoneNumber(x))` →
+ * `maskPhone`(masking.ts) 파이프라인. maskPhone 은 부분 문자열 단위로 매칭하므로
+ * 형식이 보장되지 않은 원본을 직접 넣지 말고 이 경로로 정형화한 뒤 마스킹할 것.
+ */
+/** 전화번호 분류 — 3언어 공유 소문자 타입 문자열. */
+type PhoneType = "mobile" | "landline" | "voip" | "safe" | "m2m" | "unknown";
+/**
+ * 구분자(하이픈·스페이스·탭·괄호·점)를 제거하고, `+82` 접두는 `0` 을 보충해
+ * 국내 표기로 역변환한다 (`"+82 10-1234-5678"` → `"01012345678"`).
+ * 이미 `0` 으로 시작하는 `+82 010…` 표기는 `0` 을 중복 보충하지 않는다
+ * (Java/Python 동일 규칙). 그 외 문자는 보존한다(분류 단계에서 unknown 처리).
+ */
+declare function normalizePhoneNumber(value: string): string;
+/**
+ * 정규화 후 번호를 분류한다. 표에 없는 패턴·비숫자 포함은 `"unknown"`.
+ * - mobile: 010(11자리), 011/016/017/018/019(10~11자리)
+ * - landline: 02(9~10자리), 지역번호 표(10~11자리)
+ * - voip: 070(11자리) / safe: 050X(11~12자리) / m2m: 012(11~12자리)
+ */
+declare function classifyPhoneNumber(value: string): PhoneType;
+/**
+ * 정규화 후 표준 하이픈 그룹핑으로 포맷한다. 그룹핑 불가(unknown·비표준 길이)면
+ * **정규화 문자열을 그대로 반환**한다 (예외 없음).
+ * - 02: 2-3-4(9자리) / 2-4-4(10자리)
+ * - 3자리 식별번호(이동·지역·070·012 11자리): 3-3-4(10자리) / 3-4-4(11자리)
+ * - 050X: 4-3-4(11자리) / 4-4-4(12자리)
+ */
+declare function formatPhoneNumber(value: string): string;
+/**
+ * E.164(`+82…`) 표기로 변환한다 — 분류 성공 시 선행 `0` 을 떼고 `+82` 를 붙인다.
+ * `"unknown"` 은 null. 역변환(`+82` → `0…`)은 {@link normalizePhoneNumber} 가 담당.
+ */
+declare function toE164(value: string): string | null;
+
+/**
+ * 금액 한글 표기 3종 — 한글 수사·공문서 갖은자 표기·UI 축약.
+ *
+ * 원천: Java `KoreanAmountUtils` / Python `money.py` 와 동일 규칙 (수동 동기화).
+ *
+ * 지원 범위: `|amount| < 10^20` (만·억·조·경). 입력은 `number`(안전 정수) 또는
+ * `bigint` — 비정수·비안전 정수·범위 초과는 RangeError.
+ * 축약은 **내림**을 채택한다(금액 과대 표시 방지).
+ */
+/**
+ * 순수 한글 수사 표기 — `12345678` → `"천이백삼십사만오천육백칠십팔"`.
+ * 그룹 내 1 은 십/백/천 앞에서 생략하고, 그룹값 1 은 "일만/일억" 으로 명시한다.
+ * 0 은 `"영"`, 음수는 `"마이너스 "` 접두.
+ */
+declare function toKoreanWords(amount: number | bigint): string;
+/**
+ * 공문서 위조방지 표기 — `"금" + 전자리 명시 수사(일십·일백·일천 포함) + "원整"`.
+ * `12345678` → `"금일천이백삼십사만오천육백칠십팔원整"`, 0 → `"금영원整"`.
+ * 음수는 RangeError (공문서 금액에 음수 없음).
+ */
+declare function toFormalNotation(amount: number | bigint): string;
+/**
+ * UI 축약 표기 — 소수 1자리 **내림**(금액 과대 표시 방지), `.0` 생략, 정수부 콤마.
+ * - ≥1조 → `"X.Y조"` / ≥1억 → `"X.Y억"` / ≥1만 → 만 단위 내림 콤마 `"N,NNN만"`
+ * - <1만 → 콤마 숫자 그대로(단위·"원" 없음), 음수는 `-` 접두.
+ */
+declare function abbreviateAmount(amount: number | bigint): string;
+
+/**
+ * 영업일 계산기 — 공휴일 데이터 주입형.
+ *
+ * 원천: Java `BusinessDays` / Python `business_days.py` 와 동일 규칙 (수동 동기화).
+ *
+ * **내장 공휴일 테이블은 없다** — 한국 공휴일은 대체공휴일·임시공휴일 등으로
+ * 매년 변하므로 라이브러리에 박제하지 않고 소비자가 주입한다.
+ *
+ * 날짜는 **`"YYYY-MM-DD"` 문자열 고정** (`Date` 객체 금지 — 타임존 함정 차단).
+ * 형식 위반·실존하지 않는 날짜는 RangeError. 내부 요일·가감 연산은 UTC 기준
+ * epoch day 산술이라 실행 환경 타임존의 영향을 받지 않는다.
+ */
+/** 영업일 계산기 — {@link createBusinessDays} 로 생성한다. */
+interface BusinessDays {
+    /** 영업일 여부 — 주말(토·일) 또는 주입된 공휴일이면 false. */
+    isBusinessDay(date: string): boolean;
+    /**
+     * 영업일 n일 가감(n 음수 허용). **n=0 은 입력 날짜 그대로 반환한다(스냅 없음)** —
+     * 비영업일 입력도 그대로.
+     */
+    addBusinessDays(date: string, n: number): string;
+    /** 다음 영업일 (엄격 초과 — 입력이 영업일이어도 그다음을 찾는다). */
+    nextBusinessDay(date: string): string;
+    /** 이전 영업일 (엄격 미만). */
+    previousBusinessDay(date: string): string;
+    /** 반개구간 `[start, endExclusive)` 의 영업일 수. `start > end` 는 RangeError. */
+    countBusinessDays(start: string, endExclusive: string): number;
+}
+interface BusinessDaysOptions {
+    /** 공휴일 목록 — `"YYYY-MM-DD"` 문자열 (불변 복사). */
+    holidays: Iterable<string>;
+}
+/**
+ * 공휴일을 주입해 영업일 계산기를 만든다.
+ *
+ * ```ts
+ * const bd = createBusinessDays({ holidays: ["2026-01-01"] });
+ * bd.addBusinessDays("2025-12-31", 1); // "2026-01-02" — 1/1 스킵
+ * ```
+ */
+declare function createBusinessDays(options: BusinessDaysOptions): BusinessDays;
+
+/**
+ * 한글 자모 분해·결합 + 혼합 질의 전방일치 매처.
+ *
+ * 원천: Java `HangulUtils` / Python `text/jamo.py` 와 동일 규칙 (수동 동기화).
+ * 초성만 뽑는 기존 `chosung.ts`(무변경·하위호환)와 별개 모듈이다.
+ *
+ * 분해 정책(확정): **두벌식 키보드 자모열** — 초성·중성·종성을 호환 자모
+ * (U+3131~U+3163)로 펼치되,
+ * - 복합 모음 분해: ㅘ→ㅗㅏ, ㅙ→ㅗㅐ, ㅚ→ㅗㅣ, ㅝ→ㅜㅓ, ㅞ→ㅜㅔ, ㅟ→ㅜㅣ, ㅢ→ㅡㅣ
+ * - 겹받침 분해: ㄳ→ㄱㅅ, ㄵ→ㄴㅈ, ㄶ→ㄴㅎ, ㄺ→ㄹㄱ, ㄻ→ㄹㅁ, ㄼ→ㄹㅂ,
+ *   ㄽ→ㄹㅅ, ㄾ→ㄹㅌ, ㄿ→ㄹㅍ, ㅀ→ㄹㅎ, ㅄ→ㅂㅅ
+ * - **쌍자음(ㄲㄸㅃㅆㅉ·종성 ㄲㅆ)은 분해하지 않는다**(시프트 입력 = 단일 타건)
+ * - 완성 음절이 아닌 문자(비한글·단독 자모)는 그대로 통과 — 단독 복합 자모
+ *   (ㅘ·ㄳ 등)도 분해하지 않는다 (Java/Python 동일 정책)
+ *
+ * 결합은 역변환(왼쪽부터 탐욕) — 완성 음절 입력 기준 `compose(decompose(s)) == s`
+ * 왕복이 보장된다. 음절을 이루지 못하는 자모는 그대로 출력한다.
+ */
+/**
+ * 문자열을 두벌식 키보드 자모열로 분해한다 (`"값"` → `"ㄱㅏㅂㅅ"`).
+ * 완성 음절은 초·중·종성으로, 복합 모음·겹받침은 구성 자모로 펼친다.
+ * 쌍자음은 분해하지 않고, 완성 음절이 아닌 문자(비한글·단독 자모)는 그대로
+ * 통과한다 (Java `HangulUtils.decompose` / Python `jamo.decompose` 동일 정책).
+ */
+declare function decomposeHangul(s: string): string;
+/**
+ * 자모열을 완성 음절로 결합한다 — {@link decomposeHangul} 의 역변환(왼쪽부터 탐욕).
+ * 초성→중성(다음 모음과 복합 결합 시도)→종성(다음 문자가 모음이면 초성으로 양보,
+ * 겹받침 결합 후에도 다음이 모음이면 둘째를 양보) 순으로 채운다.
+ * 음절을 이루지 못하는 자모·비한글 문자는 그대로 출력한다.
+ */
+declare function composeHangul(s: string): string;
+/**
+ * 혼합 질의 전방일치 매처 — 완성 음절·단독 자음·진행 중 음절이 섞인 질의가
+ * 대상의 접두인지 판정한다 (`matchesHangul("ㅎ길", "홍길동")` → true).
+ *
+ * - 마지막이 아닌 질의 문자: 완성 음절은 대상과 정확 일치, 단독 자음(ㄱ~ㅎ)은
+ *   대상 음절의 초성 일치, 비한글은 소문자화 후 비교(toChosung 관례)
+ * - 마지막 질의 문자: **자모열 전방일치** — `decompose(질의)` 가
+ *   `decompose(대상)` 의 접두면 매치 (`"셔"`→`"션"`, `"ㄷ"`→`"동"` 커버)
+ * - 빈 질의는 true, 질의가 대상보다 길면 false
+ */
+declare function matchesHangul(query: string, target: string): boolean;
+
+export { type ApiClient, type ApiClientConfig, type ApiClientRetryOptions, ApiError, type ApiErrorInfo, type ApiRequestInfo, type ApiResponseInfo, type ApiResult, type BulkResult, type BulkResultBuilder, type BulkResultItem, type Bulkhead, BulkheadFullError, type BulkheadOptions, type BusinessDays, type BusinessDaysOptions, type CircuitBreaker, type CircuitBreakerOptions, CircuitOpenError, type CircuitState, type CommonResponse, type FeatureFlagReader, type FieldErrorDetail, type FileKind, type JosaPair, type ListQueryOptions, type PageResponse, type PhoneType, ResultCode, type RetryOptions, type SortParam, type SseCallbacks, type SseFrameEvent, type SseSource, type TokenBucket, type TokenBucketOptions, type TtlCache, type TtlCacheOptions, type UploadValidationResult, type ValidationErrorData, WEBHOOK_SIGNATURE_HEADER, abbreviateAmount, ageByYear, ageInsurance, ageMan, attachJosa, buildListQuery, bulkFailures, classifyPhoneNumber, composeHangul, createApiClient, createBulkResultBuilder, createBulkhead, createBusinessDays, createCircuitBreaker, createFeatureFlags, createTokenBucket, createTtlCache, decodeJwtPayload, decomposeHangul, formatPhoneNumber, generateIdempotencyKey, getTokenExpiry, isBulkResult, isChosungQuery, isForeignerRrn, isRetryableStatus, isTokenExpired, isValidBusinessNumber, isValidCorporateNumber, isValidRrn, isValidationErrorData, kindsForExtension, maskCardNumber, maskEmail, maskName, maskPhone, maskSecret, matchesHangul, normalizeBusinessNumber, normalizePhoneNumber, normalizeRrn, parseFlag, parseRetryAfterMs, parseSseFrame, parseWireDateTime, pickJosa, readSseStream, retry, rrnBirthDate, rrnChecksumOkLegacy, sanitizeLogValue, signWebhook, sniffFile, stripZone, toChosung, toE164, toFormalNotation, toKoreanWords, toWireDate, toWireDateTime, validateUpload, verifyWebhook };